codex-configurator 0.2.2 → 0.2.3

package/README.md

@@ -38,6 +38,7 @@ npm start
 - `PgUp` `PgDn`: move one page up/down
 - `Home` `End`: jump to first/last item
 - `Enter`: open selected table; for boolean settings, toggle directly; for string settings, open inline input; for other preset values, open picker
+- `/`: start fuzzy filter mode for the current list
 - `Del`: unset selected value or remove selected custom `<id>` entry from `config.toml`
 - `←` / `Backspace`: move up one level (to parent table)
 - `r`: reload the active config file
@@ -47,7 +48,10 @@ The right-hand pane shows what each setting means, plus a picker when a value ha
 Deprecated settings are marked with a `[!]` warning marker; only that marker is highlighted.
 Model picker entries are curated presets maintained by this project.
 In select lists, `[default]` marks the default option.
-The header banner shows the configurator package version (for example `v0.2.1`) next to the wordmark.
+The header banner shows the configurator package version (for example `v0.2.2`) next to the wordmark.
+Section help includes purpose-driven guidance (what a section is for), not generic placeholder copy.
+Fuzzy filter mode matches section/value rows by label and key as you type.
+The list panel shows a breadcrumb title on its top border with your current path (for example `projects > /home/me/repo`).
 
 ## TOML-aware navigation
 
@@ -104,6 +108,15 @@ You can override either command with:
 - `CODEX_CONFIGURATOR_CODEX_BIN=<command-or-path>`
 - `CODEX_CONFIGURATOR_NPM_BIN=<command-or-path>`
 
+## Self-update behavior
+
+On startup, the app checks the npm registry for the latest `codex-configurator` version.
+If the running version is older, it automatically runs:
+
+- `npm install -g codex-configurator@latest`
+
+This uses the `npm` command from `PATH` (or `CODEX_CONFIGURATOR_NPM_BIN` if set).
+
 ## Upstream reference
 
 - Codex configuration reference: https://developers.openai.com/codex/config-reference/

package/index.js

@@ -4,7 +4,7 @@ import React, { useState, useEffect } from 'react';
 import { execFile } from 'node:child_process';
 import { createRequire } from 'node:module';
 import { render, useInput, useApp, useStdout, Text, Box } from 'ink';
-import { CONTROL_HINT, EDIT_CONTROL_HINT } from './src/constants.js';
+import { CONTROL_HINT, EDIT_CONTROL_HINT, FILTER_CONTROL_HINT } from './src/constants.js';
 import {
   readConfig,
   getNodeAtPath,
@@ -30,6 +30,7 @@ import {
 } from './src/interaction.js';
 import { Header } from './src/components/Header.js';
 import { ConfigNavigator } from './src/components/ConfigNavigator.js';
+import { filterRowsByQuery } from './src/fuzzySearch.js';
 
 const require = createRequire(import.meta.url);
 const { version: PACKAGE_VERSION = 'unknown' } = require('./package.json');
@@ -61,31 +62,43 @@ const isCustomIdTableRow = (pathSegments, row) =>
 
 const isInlineTextMode = (mode) => mode === 'text' || mode === 'add-id';
 const VERSION_COMMAND_TIMEOUT_MS = 3000;
+const UPDATE_COMMAND_TIMEOUT_MS = 180000;
+const COMMAND_MAX_BUFFER_BYTES = 1024 * 1024;
+const UPDATE_MAX_BUFFER_BYTES = 10 * 1024 * 1024;
 const CODEX_BIN_ENV_VAR = 'CODEX_CONFIGURATOR_CODEX_BIN';
 const NPM_BIN_ENV_VAR = 'CODEX_CONFIGURATOR_NPM_BIN';
+const CONFIGURATOR_PACKAGE_NAME = 'codex-configurator';
 
-const runCommand = (command, args = []) =>
+const runCommandWithResult = (command, args = [], options = {}) =>
   new Promise((resolve) => {
     execFile(
       command,
       args,
       {
         encoding: 'utf8',
-        timeout: VERSION_COMMAND_TIMEOUT_MS,
-        maxBuffer: 1024 * 1024,
+        timeout: options.timeout || VERSION_COMMAND_TIMEOUT_MS,
+        maxBuffer: options.maxBuffer || COMMAND_MAX_BUFFER_BYTES,
         windowsHide: true,
       },
-      (error, stdout) => {
-        if (error) {
-          resolve('');
-          return;
-        }
-
-        resolve(String(stdout || '').trim());
+      (error, stdout, stderr) => {
+        resolve({
+          ok: !error,
+          stdout: String(stdout || '').trim(),
+          stderr: String(stderr || '').trim(),
+        });
       }
     );
   });
 
+const runCommand = async (command, args = [], options = {}) => {
+  const result = await runCommandWithResult(command, args, options);
+  if (!result.ok) {
+    return '';
+  }
+
+  return result.stdout;
+};
+
 const getConfiguredCommand = (environmentVariableName, fallbackCommand) => {
   const configuredCommand = String(process.env[environmentVariableName] || '').trim();
   return configuredCommand || fallbackCommand;
@@ -96,6 +109,24 @@ const getVersionCommands = () => ({
   npmCommand: getConfiguredCommand(NPM_BIN_ENV_VAR, 'npm'),
 });
 
+const getLatestPackageVersion = async (npmCommand, packageName) => {
+  const latestOutput = await runCommand(npmCommand, ['view', packageName, 'version', '--json']);
+  return normalizeVersion(latestOutput) || latestOutput.trim();
+};
+
+const updateGlobalPackageToLatest = async (npmCommand, packageName) => {
+  const result = await runCommandWithResult(
+    npmCommand,
+    ['install', '-g', `${packageName}@latest`],
+    {
+      timeout: UPDATE_COMMAND_TIMEOUT_MS,
+      maxBuffer: UPDATE_MAX_BUFFER_BYTES,
+    }
+  );
+
+  return result.ok;
+};
+
 const getCodexVersion = async (codexCommand) => {
   const output = await runCommand(codexCommand, ['--version']);
   const firstLine = output.split('\n')[0]?.trim();
@@ -185,6 +216,24 @@ const getCodexUpdateStatus = async () => {
   };
 };
 
+const ensureLatestConfiguratorVersion = async (npmCommand) => {
+  const installed = normalizeVersion(PACKAGE_VERSION);
+  if (!installed) {
+    return;
+  }
+
+  const latest = await getLatestPackageVersion(npmCommand, CONFIGURATOR_PACKAGE_NAME);
+  if (!latest) {
+    return;
+  }
+
+  if (compareVersions(installed, latest) >= 0) {
+    return;
+  }
+
+  await updateGlobalPackageToLatest(npmCommand, CONFIGURATOR_PACKAGE_NAME);
+};
+
 const App = () => {
   const isInteractive = process.stdin.isTTY && process.stdout.isTTY;
   const { stdout } = useStdout();
@@ -198,6 +247,8 @@ const App = () => {
   const [scrollOffset, setScrollOffset] = useState(0);
   const [editMode, setEditMode] = useState(null);
   const [editError, setEditError] = useState('');
+  const [filterQuery, setFilterQuery] = useState('');
+  const [isFilterEditing, setIsFilterEditing] = useState(false);
   const [codexVersion, setCodexVersion] = useState('version loading...');
   const [codexVersionStatus, setCodexVersionStatus] = useState('');
   const { exit } = useApp();
@@ -216,7 +267,13 @@ const App = () => {
       setCodexVersionStatus(check.status);
     };
 
+    const ensureLatestConfigurator = async () => {
+      const commands = getVersionCommands();
+      await ensureLatestConfiguratorVersion(commands.npmCommand);
+    };
+
     loadVersionStatus();
+    ensureLatestConfigurator();
 
     return () => {
       isCancelled = true;
@@ -224,7 +281,8 @@ const App = () => {
   }, []);
 
   const currentNode = getNodeAtPath(snapshot.ok ? snapshot.data : {}, pathSegments);
-  const rows = buildRows(currentNode, pathSegments);
+  const allRows = buildRows(currentNode, pathSegments);
+  const rows = filterRowsByQuery(allRows, filterQuery);
   const safeSelected = rows.length === 0 ? 0 : Math.min(selectedIndex, rows.length - 1);
   const listViewportHeight = computeListViewportHeight(rows, terminalHeight);
   const currentPathKey = pathToKey(pathSegments);
@@ -441,11 +499,51 @@ const App = () => {
   useInput((input, key) => {
     const isTextEditing = isInlineTextMode(editMode?.mode);
 
+    if (isFilterEditing) {
+      if (key.return || key.escape) {
+        setIsFilterEditing(false);
+        return;
+      }
+
+      if ((key.ctrl && key.name === 'u') || input === '\u0015') {
+        setFilterQuery('');
+        return;
+      }
+
+      if (isDeleteKey(input, key) || isBackspaceKey(input, key)) {
+        setFilterQuery((previous) => previous.slice(0, -1));
+        return;
+      }
+
+      if (
+        key.rightArrow ||
+        key.leftArrow ||
+        key.upArrow ||
+        key.downArrow ||
+        isPageUpKey(input, key) ||
+        isPageDownKey(input, key) ||
+        isHomeKey(input, key) ||
+        isEndKey(input, key)
+      ) {
+        return;
+      }
+
+      if (!key.ctrl && !key.meta && input.length > 0) {
+        setFilterQuery((previous) => `${previous}${input}`);
+      }
+      return;
+    }
+
     if (input === 'q' && !isTextEditing) {
       exit();
       return;
     }
 
+    if (!editMode && input === '/') {
+      setIsFilterEditing(true);
+      return;
+    }
+
     if (editMode) {
       if (isInlineTextMode(editMode.mode)) {
         if (key.return) {
@@ -776,6 +874,8 @@ const App = () => {
         scrollOffset: 0,
         editMode: null,
         editError: editError,
+        filterQuery,
+        isFilterEditing,
       }),
       React.createElement(Text, { color: 'yellow' }, 'Non-interactive mode: input is disabled.')
     );
@@ -798,8 +898,14 @@ const App = () => {
       scrollOffset,
       editMode,
       editError,
+      filterQuery,
+      isFilterEditing,
     }),
-    React.createElement(Text, { color: 'gray' }, editMode ? EDIT_CONTROL_HINT : CONTROL_HINT)
+    React.createElement(
+      Text,
+      { color: 'gray' },
+      isFilterEditing ? FILTER_CONTROL_HINT : editMode ? EDIT_CONTROL_HINT : CONTROL_HINT
+    )
   );
 };
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "codex-configurator",
-	"version": "0.2.2",
+	"version": "0.2.3",
 	"description": "TOML-aware Ink TUI for Codex Configurator",
 	"main": "index.js",
 	"type": "module",

package/src/components/ConfigNavigator.js

@@ -8,6 +8,7 @@ import {
 } from '../configHelp.js';
 import { computePaneWidths, clamp } from '../layout.js';
 import { getNodeAtPath, buildRows } from '../configParser.js';
+import { filterRowsByQuery } from '../fuzzySearch.js';
 
 const MenuItem = ({ isSelected, isDimmed, isDeprecated, label }) =>
   React.createElement(
@@ -98,6 +99,45 @@ const renderIdEditor = (placeholder, draftValue) =>
     React.createElement(Text, { color: 'gray' }, 'Type id • Enter: create • Esc: cancel')
   );
 
+const formatBreadcrumbSegment = (segment) => {
+  const value = String(segment);
+  return /^\d+$/.test(value) ? `[${value}]` : value;
+};
+
+const formatBreadcrumbs = (pathSegments) => {
+  if (!Array.isArray(pathSegments) || pathSegments.length === 0) {
+    return '';
+  }
+
+  return pathSegments.map(formatBreadcrumbSegment).join(' > ');
+};
+
+const formatSectionSummary = (row) => {
+  if (row?.kind === 'table') {
+    const entryCount =
+      Object.prototype.toString.call(row?.value) === '[object Object]'
+        ? Object.keys(row.value).length
+        : 0;
+
+    if (entryCount === 0) {
+      return 'Empty section.';
+    }
+
+    return `Section with ${entryCount} configured ${entryCount === 1 ? 'entry' : 'entries'}.`;
+  }
+
+  if (row?.kind === 'tableArray') {
+    const entryCount = Array.isArray(row?.value) ? row.value.length : 0;
+    if (entryCount === 0) {
+      return 'Section with no entries.';
+    }
+
+    return `Section list with ${entryCount} ${entryCount === 1 ? 'entry' : 'entries'}.`;
+  }
+
+  return 'This section groups related settings.';
+};
+
 const renderEditableOptions = (
   options,
   selectedOptionIndex,
@@ -181,14 +221,15 @@ const formatConfigHelp = (pathSegments, row) => {
   }
 
   const info = getConfigHelp(pathSegments, row.key);
+  const isSectionRow = row.kind === 'table' || row.kind === 'tableArray';
   const defaultCollectionText =
-    row.kind === 'table' || row.kind === 'tableArray'
-      ? 'This section groups related settings.'
+    isSectionRow
+      ? formatSectionSummary(row)
       : row.kind === 'array'
         ? `This is a list with ${row.value.length} entries.`
         : 'This setting affects Codex behavior.';
   const short = info?.short || defaultCollectionText;
-  const usage = info?.usage;
+  const usage = isSectionRow ? null : info?.usage;
   const isWarning = Boolean(info?.deprecation);
   const lines = [{ text: short, color: 'white', bold: false, showWarningIcon: false }];
 
@@ -240,6 +281,8 @@ export const ConfigNavigator = ({
   terminalHeight,
   editMode,
   editError,
+  filterQuery = '',
+  isFilterEditing = false,
 }) => {
   if (!snapshot.ok) {
     return React.createElement(
@@ -252,9 +295,13 @@ export const ConfigNavigator = ({
   }
 
   const currentNode = getNodeAtPath(snapshot.data, pathSegments);
-  const rows = buildRows(currentNode, pathSegments);
+  const allRows = buildRows(currentNode, pathSegments);
+  const rows = filterRowsByQuery(allRows, filterQuery);
+  const breadcrumbs = formatBreadcrumbs(pathSegments);
   const selected = rows.length === 0 ? 0 : Math.min(selectedIndex, rows.length - 1);
-  const { leftWidth, rightWidth } = computePaneWidths(terminalWidth, rows);
+  const paneSizingRows = breadcrumbs ? [...rows, { label: breadcrumbs }] : rows;
+  const { leftWidth, rightWidth } = computePaneWidths(terminalWidth, paneSizingRows);
+  const breadcrumbLabel = breadcrumbs ? truncate(breadcrumbs, Math.max(8, leftWidth - 6)) : '';
   const terminalListHeight = Math.max(4, (terminalHeight || 24) - 14);
   const viewportHeight = Math.max(4, Math.min(rows.length, Math.min(20, terminalListHeight)));
   const viewportStart = clamp(scrollOffset, 0, Math.max(0, rows.length - viewportHeight));
@@ -292,96 +339,138 @@ export const ConfigNavigator = ({
   return React.createElement(
     Box,
     { flexDirection: 'row', gap: 2 },
-    React.createElement(
-      Box,
-      { flexDirection: 'column', width: leftWidth },
       React.createElement(
         Box,
-        {
-          flexDirection: 'column',
-          borderStyle: 'single',
-          borderColor: 'gray',
-          padding: 1,
-        },
-        rows.length === 0
-          ? React.createElement(Text, { color: 'gray' }, '[no entries in this table]')
-          : visibleRows.map((row, viewIndex) => {
-              const index = viewportStart + viewIndex;
-              const showTopCue = canScrollUp && viewIndex === 0;
-              const showBottomCue = canScrollDown && viewIndex === visibleRows.length - 1;
-              const isSelected = index === selected;
-              const label = `${showTopCue ? '↑ ' : showBottomCue ? '↓ ' : '  '}${isSelected ? '▶' : ' '} ${row.label}`;
-
-              return React.createElement(
-                MenuItem,
-                {
-                  label,
-                  isSelected,
-                  isDimmed: !isSelected && row.isConfigured === false,
-                  isDeprecated: row.isDeprecated,
-                  key: `left-${index}`,
-                }
-              );
-            })
-      )
-    ),
-    React.createElement(
-      Box,
-      { flexDirection: 'column', width: rightWidth, marginTop: 2 },
-      rows.length === 0
-        ? React.createElement(Text, { color: 'gray' }, 'No selection available.')
-        : React.createElement(
-            React.Fragment,
-            null,
-              ...formatConfigHelp(pathSegments, rows[selected]).map((line, lineIndex) =>
-                React.createElement(
-                  Text,
+        { flexDirection: 'column', width: leftWidth },
+        React.createElement(
+          Box,
+          {
+            flexDirection: 'column',
+            borderStyle: 'single',
+            borderColor: 'gray',
+            padding: 1,
+          },
+          rows.length === 0
+            ? React.createElement(
+                Text,
+                { color: 'gray' },
+                String(filterQuery || '').trim().length > 0
+                  ? '[no entries match current filter]'
+                  : '[no entries in this table]'
+              )
+            : visibleRows.map((row, viewIndex) => {
+                const index = viewportStart + viewIndex;
+                const showTopCue = canScrollUp && viewIndex === 0;
+                const showBottomCue = canScrollDown && viewIndex === visibleRows.length - 1;
+                const isSelected = index === selected;
+                const label = `${showTopCue ? '↑ ' : showBottomCue ? '↓ ' : '  '}${isSelected ? '▶' : ' '} ${row.label}`;
+
+                return React.createElement(
+                  MenuItem,
                   {
-                    key: `help-${selected}-${lineIndex}`,
-                    color: line.color,
-                    bold: line.bold,
-                  },
-                  line.showWarningIcon
-                    ? React.createElement(Text, { color: 'yellow' }, '[!] ')
-                    : null,
-                  line.text
-                )
-              ),
-            editError ? React.createElement(Text, { color: 'red' }, editError) : null,
-            editMode ? React.createElement(Text, { color: 'gray' }, ' ') : null,
-            editMode
-              ? editMode.mode === 'text'
-                ? renderTextEditor(editMode.draftValue)
-                : editMode.mode === 'add-id'
-                  ? renderIdEditor(editMode.placeholder, editMode.draftValue)
-                : renderEditableOptions(
-                    editMode.options,
-                    editMode.selectedOptionIndex,
-                    editDefaultOptionIndex,
-                    editMode.path.slice(0, -1),
-                    rows[selected].key,
-                    editMode.savedOptionIndex,
-                    true
+                    label,
+                    isSelected,
+                    isDimmed: !isSelected && row.isConfigured === false,
+                    isDeprecated: row.isDeprecated,
+                    key: `left-${index}`,
+                  }
+                );
+              })
+        ),
+        React.createElement(
+          Box,
+          { position: 'absolute', top: 0, left: 0 },
+          breadcrumbLabel
+            ? React.createElement(
+                Text,
+                null,
+                React.createElement(Text, { color: 'gray' }, '┌── '),
+                React.createElement(Text, { color: 'cyan' }, `${breadcrumbLabel} `)
+              )
+            : null
+        )
+      ),
+      React.createElement(
+        Box,
+        { flexDirection: 'column', width: rightWidth, marginTop: 1 },
+        rows.length === 0
+          ? React.createElement(
+              React.Fragment,
+              null,
+              String(filterQuery || '').trim().length > 0
+                ? React.createElement(
+                    Text,
+                    { color: 'gray' },
+                    `Filter: ${filterQuery} (${rows.length}/${allRows.length})`
                   )
-              : shouldShowReadOnlyOptions
+                : null,
+              React.createElement(
+                Text,
+                { color: 'gray' },
+                String(filterQuery || '').trim().length > 0
+                  ? 'No selection available. Adjust or clear the filter.'
+                  : 'No selection available.'
+              )
+            )
+          : React.createElement(
+              React.Fragment,
+              null,
+                String(filterQuery || '').trim().length > 0 || isFilterEditing
                   ? React.createElement(
-                      React.Fragment,
-                      null,
-                      React.createElement(Text, { color: 'gray' }, ' '),
-                      renderEditableOptions(
-                        readOnlyOptions,
-                        readOnlyOptionIndex,
-                        readOnlyDefaultOptionIndex,
-                        selectedPath,
-                        selectedRow?.key,
+                      Text,
+                      { color: 'cyan' },
+                      `Filter: ${filterQuery || ''} (${rows.length}/${allRows.length})${isFilterEditing ? ' [editing]' : ''}`
+                    )
+                  : null,
+                ...formatConfigHelp(pathSegments, rows[selected]).map((line, lineIndex) =>
+                  React.createElement(
+                    Text,
+                    {
+                      key: `help-${selected}-${lineIndex}`,
+                      color: line.color,
+                      bold: line.bold,
+                    },
+                    line.showWarningIcon
+                      ? React.createElement(Text, { color: 'yellow' }, '[!] ')
+                      : null,
+                    line.text
+                  )
+                ),
+              editError ? React.createElement(Text, { color: 'red' }, editError) : null,
+              editMode ? React.createElement(Text, { color: 'gray' }, ' ') : null,
+              editMode
+                ? editMode.mode === 'text'
+                  ? renderTextEditor(editMode.draftValue)
+                  : editMode.mode === 'add-id'
+                    ? renderIdEditor(editMode.placeholder, editMode.draftValue)
+                  : renderEditableOptions(
+                      editMode.options,
+                      editMode.selectedOptionIndex,
+                      editDefaultOptionIndex,
+                      editMode.path.slice(0, -1),
+                      rows[selected].key,
+                      editMode.savedOptionIndex,
+                      true
+                    )
+                : shouldShowReadOnlyOptions
+                    ? React.createElement(
+                        React.Fragment,
                         null,
-                        false
+                        React.createElement(Text, { color: 'gray' }, ' '),
+                        renderEditableOptions(
+                          readOnlyOptions,
+                          readOnlyOptionIndex,
+                          readOnlyDefaultOptionIndex,
+                          selectedPath,
+                          selectedRow?.key,
+                          null,
+                          false
+                        )
                       )
-                    )
-                  : rows[selected].kind === 'array'
-                      ? renderArrayDetails(rows[selected].value)
-                      : null
-          )
-    )
+                    : rows[selected].kind === 'array'
+                        ? renderArrayDetails(rows[selected].value)
+                        : null
+            )
+      )
   );
 };

package/src/configHelp.js

@@ -2,7 +2,12 @@ import {
   getConfigFeatureDefinition,
   getConfigFeatureDefinitionOrFallback,
 } from './configFeatures.js';
-import { getReferenceOptionForPath } from './configReference.js';
+import {
+  getReferenceOptionForPath,
+  getReferenceCustomIdPlaceholder,
+  getReferenceDescendantOptions,
+  getReferenceTableDefinitions,
+} from './configReference.js';
 
 const CONFIG_VALUE_OPTIONS = {
   model: [
@@ -54,6 +59,24 @@ const CONFIG_OPTION_EXPLANATIONS = {
     untrusted: 'Limits risky actions and prompts more often.',
   },
 };
+const SECTION_PURPOSE_OVERRIDES = {
+  agents: 'Named agent definitions and per-agent configuration file references.',
+  apps: 'Per-app enablement rules and disable reasons.',
+  features: 'Feature flags for optional and experimental Codex behavior.',
+  feedback: 'Feedback submission settings for Codex surfaces.',
+  history: 'Session history retention policy and on-disk size limits.',
+  mcp_servers: 'MCP server definitions, transport settings, and authentication configuration.',
+  model_providers: 'Model provider definitions, API endpoints, and credential settings.',
+  notice: 'Visibility toggles for startup and migration notices.',
+  otel: 'OpenTelemetry exporter configuration for telemetry and traces.',
+  profiles: 'Named profile overrides you can select per session.',
+  projects: 'Project/worktree trust settings scoped by filesystem path.',
+  sandbox_workspace_write: 'Workspace-write sandbox behavior, writable roots, and network access rules.',
+  shell_environment_policy: 'Shell environment inheritance and variable override policy.',
+  skills: 'Skill discovery and loading controls.',
+  tools: 'Tool-related configuration, including legacy compatibility flags.',
+  tui: 'Terminal UI behavior, notifications, and presentation settings.',
+};
 
 const makePathSegments = (segments, key) => {
   const normalizedSegments = Array.isArray(segments)
@@ -78,6 +101,73 @@ const getContextEntry = (segments, key, candidates) => {
 
 const getReferenceEntry = (segments, key) => getReferenceOptionForPath(makePathSegments(segments, key));
 
+const formatPlaceholderLabel = (placeholder) => {
+  const cleaned = String(placeholder || '')
+    .replace(/^</, '')
+    .replace(/>$/, '');
+
+  return cleaned || 'id';
+};
+
+const toFirstSentence = (text) => {
+  const normalized = String(text || '').replace(/\s+/g, ' ').trim();
+  if (!normalized) {
+    return '';
+  }
+
+  const periodIndex = normalized.indexOf('. ');
+  if (periodIndex < 0) {
+    return normalized;
+  }
+
+  return normalized.slice(0, periodIndex + 1);
+};
+
+const getSectionPurposeDescription = (descendantOptions) => {
+  for (const option of descendantOptions) {
+    const firstSentence = toFirstSentence(option?.description);
+    if (firstSentence) {
+      return firstSentence;
+    }
+  }
+
+  return '';
+};
+
+const buildInferredSectionHelp = (segments, key) => {
+  const sectionPath = makePathSegments(segments, key);
+  const childDefinitions = getReferenceTableDefinitions(sectionPath);
+  const descendantOptions = getReferenceDescendantOptions(sectionPath);
+  const customPlaceholder = getReferenceCustomIdPlaceholder(sectionPath);
+  const parentCustomPlaceholder = getReferenceCustomIdPlaceholder(sectionPath.slice(0, -1));
+
+  if (childDefinitions.length === 0 && descendantOptions.length === 0 && !customPlaceholder) {
+    return null;
+  }
+
+  const rootOverride = sectionPath.length === 1
+    ? SECTION_PURPOSE_OVERRIDES[sectionPath[0]]
+    : null;
+  const customLabel = customPlaceholder ? formatPlaceholderLabel(customPlaceholder) : '';
+  const bestPurposeDescription = getSectionPurposeDescription(descendantOptions);
+  const dynamicEntryLabel = parentCustomPlaceholder
+    ? formatPlaceholderLabel(parentCustomPlaceholder)
+    : '';
+  const short = rootOverride
+    || (dynamicEntryLabel
+      ? `Configuration for this ${dynamicEntryLabel} entry.`
+      : '')
+    || bestPurposeDescription
+    || (customLabel
+      ? `Section for custom ${customLabel} entries.`
+      : 'Section with related settings.');
+
+  return {
+    short,
+    usage: null,
+  };
+};
+
 const getReferenceUsage = (entry) => {
   if (entry.deprecated) {
     return 'This option is deprecated in the official configuration reference.';
@@ -92,7 +182,7 @@ const getReferenceUsage = (entry) => {
   }
 
   if (entry.type === 'table') {
-    return 'This section groups related settings.';
+    return 'Press Enter to open this section and edit nested settings.';
   }
 
   if (entry.type.startsWith('array<')) {
@@ -144,6 +234,11 @@ export const getConfigHelp = (segments, key) => {
     return referenceHelp;
   }
 
+  const inferredSectionHelp = buildInferredSectionHelp(segments, key);
+  if (inferredSectionHelp) {
+    return inferredSectionHelp;
+  }
+
   return null;
 };
 

package/src/configReference.js

@@ -218,3 +218,15 @@ export const getReferenceCustomIdPlaceholder = (pathSegments = []) => {
   const [firstMatch] = [...placeholders];
   return firstMatch || null;
 };
+
+export const getReferenceDescendantOptions = (pathSegments = []) => {
+  const normalizedPath = normalizeSegments(pathSegments);
+
+  return referenceOptions
+    .filter(
+      (option) =>
+        pathPrefixMatches(option.keyPath, normalizedPath) &&
+        option.keyPath.length > normalizedPath.length
+    )
+    .sort((left, right) => left.keyPath.length - right.keyPath.length || left.key.localeCompare(right.key));
+};

package/src/constants.js

@@ -1,4 +1,5 @@
-export const CONTROL_HINT = '↑/↓ move • PgUp/PgDn page • Home/End jump • Enter: open section or edit • Del: unset value • ←/Backspace: back • r: reload • q: quit';
+export const CONTROL_HINT = '↑/↓ move • PgUp/PgDn page • Home/End jump • Enter: open section or edit • /: filter • Del: unset value • ←/Backspace: back • r: reload • q: quit';
 export const EDIT_CONTROL_HINT = '↑/↓ choose • PgUp/PgDn page • Home/End jump • Enter: save • Esc/Backspace/←: cancel • Del: delete char (text input) • r: reload • q: quit';
+export const FILTER_CONTROL_HINT = 'Type filter • Enter/Esc: done • Del/Backspace: delete • Ctrl+U: clear';
 export const BRAND = 'CODEX CONFIGURATOR';
 export const CONFIG_TAGS = ['Node.js', 'React', 'Ink', 'TOML'];

package/src/fuzzySearch.js

@@ -0,0 +1,39 @@
+const normalizeText = (value) => String(value || '').toLowerCase();
+
+export const isFuzzyMatch = (query, text) => {
+  const normalizedQuery = normalizeText(query).trim();
+  if (!normalizedQuery) {
+    return true;
+  }
+
+  const normalizedText = normalizeText(text);
+  let queryIndex = 0;
+
+  for (let textIndex = 0; textIndex < normalizedText.length; textIndex += 1) {
+    if (normalizedText[textIndex] === normalizedQuery[queryIndex]) {
+      queryIndex += 1;
+      if (queryIndex >= normalizedQuery.length) {
+        return true;
+      }
+    }
+  }
+
+  return false;
+};
+
+const rowSearchableTexts = (row) => [
+  row?.label,
+  row?.key,
+  row?.preview,
+];
+
+export const filterRowsByQuery = (rows, query) => {
+  const normalizedQuery = String(query || '').trim();
+  if (!normalizedQuery) {
+    return rows;
+  }
+
+  return rows.filter((row) =>
+    rowSearchableTexts(row).some((value) => isFuzzyMatch(normalizedQuery, value))
+  );
+};