auq-mcp-server 2.2.2 → 2.3.0

package/dist/bin/auq.js

@@ -12,46 +12,98 @@ if (command === "--help" || command === "-h") {
     console.log(`
 AUQ - Ask User Questions
 
+An MCP server and TUI for AI assistants to ask users structured questions.
+
 Usage:
   auq [command] [options]
 
 Commands:
-  (default)     Start the TUI (Terminal User Interface)
-  server        Start the MCP server (for use with MCP clients)
-  ask <json>    Ask questions via CLI (alternative to MCP)
+  (default)     Start the interactive TUI (Terminal User Interface)
+  server        Start the MCP server (for use with AI assistants)
+  ask <json>    Ask questions via CLI (pipe or argument)
 
 Options:
   --help, -h    Show this help message
   --version, -v Show version information
 
-ASK COMMAND:
-  Use 'auq ask' when you need to ask the user questions during execution.
-  This allows you to:
-  1. Gather user preferences or requirements
-  2. Clarify ambiguous instructions
-  3. Get decisions on implementation choices as you work
-  4. Offer choices to the user about what direction to take
-
-  FEATURES:
-  - Ask 1-4 structured questions via an interactive terminal interface
-  - Each question includes 2-4 multiple-choice options with explanatory descriptions
-  - Users can always provide custom free-text input as an alternative to predefined options
-  - Single-select mode (default): User picks ONE option or provides custom text
-  - Multi-select mode (multiSelect: true): User can select MULTIPLE options
-
-  USAGE NOTES:
-  - Provide a descriptive 'title' field (max 12 chars) for each question
-  - Use multiSelect: true when choices are not mutually exclusive
-  - Option labels should be concise (1-5 words)
-  - To mark a recommended option, append '(recommended)' to its label
-  - Don't include an 'Other' option - it's provided automatically
+TUI Keyboard Shortcuts:
+  Navigation:
+    ↑/↓           Navigate options
+    ←/→           Navigate questions
+    Tab/Shift+Tab Navigate questions
+
+  Selection:
+    Space         Select/toggle option (multi-select)
+    Enter         Select option & advance to next question
+    R             Select recommended option(s)
+    Ctrl+R        Quick submit (auto-select all recommended)
+
+  Session Management:
+    ]             Next session
+    [             Previous session
+    1-9           Jump to session by number
+    Ctrl+S        Open session picker
+
+  Other:
+    E             Request elaboration on current question
+    Ctrl+T        Cycle color theme
+    Esc           Reject question set
+
+Ask Command:
+  Use 'auq ask' when you need to ask the user questions during
+  execution. This allows you to:
+    1. Gather user preferences or requirements
+    2. Clarify ambiguous instructions
+    3. Get decisions on implementation choices as you work
+    4. Offer choices to the user about what direction to take
+
+  Features:
+    - Ask 1-5 structured questions via an interactive terminal UI
+    - Each question includes 2-5 multiple-choice options
+    - Users can always provide custom free-text input
+    - Single-select mode (default): pick ONE option or custom text
+    - Multi-select mode (multiSelect: true): select MULTIPLE options
+
+  Usage Notes:
+    - Provide a descriptive 'title' field (max 12 chars) per question
+    - Use multiSelect: true when choices are not mutually exclusive
+    - Option labels should be concise (1-5 words)
+    - To mark recommended, append '(recommended)' to option label
+    - Don't include an 'Other' option — it's provided automatically
 
   Returns a formatted summary of all questions and answers.
 
+Configuration:
+  Config file locations (searched in order, merged):
+    ./.auqrc.json                  Project-level (highest priority)
+    ~/.config/auq/.auqrc.json      User-level (global)
+
+  Available options (with defaults):
+    maxOptions             Max options per question (2-10, default: 5)
+    maxQuestions           Max questions per session (1-10, default: 5)
+    recommendedOptions     Recommended option count hint (default: 4)
+    recommendedQuestions   Recommended question count hint (default: 4)
+    sessionTimeout         Session timeout in ms (0 = infinite, default: 0)
+    retentionPeriod        Session retention in ms (default: 604800000 / 7d)
+    language               UI language ("auto" | "en" | "ko", default: "auto")
+    theme                  Color theme ("system" | "dark" | "light" | custom,
+                           default: "system")
+    autoSelectRecommended  Pre-select recommended options (default: true)
+    notifications.enabled  Enable desktop notifications (default: true)
+    notifications.sound    Enable notification sounds (default: true)
+
+  Custom themes: place .theme.json files in ~/.config/auq/themes/
+
+Environment Variables:
+  AUQ_SESSION_DIR    Override session storage directory
+  XDG_CONFIG_HOME    Override config base directory (default: ~/.config)
+
 Examples:
   auq                    # Start TUI (wait for questions from AI)
   auq server             # Start MCP server (for Claude Desktop, etc.)
-  auq ask '{"questions": [{"prompt": "Which language?", "title": "Lang", "options": [{"label": "TypeScript (recommended)"}, {"label": "Python"}], "multiSelect": false}]}'
+  auq ask '{"questions": [{"prompt": "Which language?", "title": "Lang",
+    "options": [{"label": "TypeScript (recommended)"}, {"label": "Python"}],
+    "multiSelect": false}]}'
   echo '{"questions": [...]}' | auq ask   # Pipe JSON to ask command
 
 For more information, visit:

package/dist/bin/tui-app.js

@@ -14,6 +14,7 @@ import { createTUIWatcher } from "../src/tui/session-watcher.js";
 import { ThemeProvider } from "../src/tui/ThemeProvider.js";
 import { ConfigProvider } from "../src/tui/ConfigContext.js";
 import { getAdjustedIndexAfterRemoval, getDirectJumpIndex, getNextSessionIndex, getPrevSessionIndex, } from "../src/tui/utils/sessionSwitching.js";
+import { KEYS } from "../src/tui/constants/keybindings.js";
 const App = ({ config }) => {
     const [state, setState] = useState({ mode: "WAITING" });
     const [sessionQueue, setSessionQueue] = useState([]);
@@ -257,12 +258,18 @@ const App = ({ config }) => {
             setShowSessionPicker(true);
             return;
         }
-        if (key.ctrl && input === "]") {
+        if (!key.ctrl && !key.meta && input === KEYS.SESSION_NEXT) {
+            if (!canUseDirectJump) {
+                return;
+            }
             const nextIndex = getNextSessionIndex(activeSessionIndex, sessionQueue.length);
             switchToSession(nextIndex);
             return;
         }
-        if (key.ctrl && input === "[") {
+        if (!key.ctrl && !key.meta && input === KEYS.SESSION_PREV) {
+            if (!canUseDirectJump) {
+                return;
+            }
             const prevIndex = getPrevSessionIndex(activeSessionIndex, sessionQueue.length);
             switchToSession(prevIndex);
             return;

package/dist/package.json

@@ -1,6 +1,6 @@
 {
     "name": "auq-mcp-server",
-    "version": "2.2.2",
+    "version": "2.3.0",
     "main": "dist/index.js",
     "bin": {
         "auq": "dist/bin/auq.js"

package/dist/src/i18n/locales/en.js

@@ -45,7 +45,7 @@ export const en = {
     },
     input: {
         customAnswerLabel: "Custom answer",
-        customAnswerHint: "(Press Tab to enter custom answer)",
+        customAnswerHint: "(Tab to submit)",
         otherCustom: "Other (custom)",
         placeholder: "Type your answer (Enter = newline, Tab = done)",
         singleLinePlaceholder: "Type here...",

package/dist/src/i18n/locales/ko.js

@@ -45,7 +45,7 @@ export const ko = {
     },
     input: {
         customAnswerLabel: "직접 입력",
-        customAnswerHint: "(Tab을 눌러 직접 입력)",
+        customAnswerHint: "(Tab으로 제출)",
         otherCustom: "기타 (직접 입력)",
         placeholder: "답변을 입력하세요 (Enter = 줄바꿈, Tab = 완료)",
         singleLinePlaceholder: "여기에 입력...",

package/dist/src/tui/ThemeProvider.js

@@ -4,6 +4,7 @@ import { ThemeContext } from "./ThemeContext.js";
 import { getTheme, listThemes, darkTheme, hasTheme } from "./themes/index.js";
 import { detectSystemTheme } from "./utils/detectTheme.js";
 import { getSavedTheme, saveTheme } from "./utils/config.js";
+import { KEYS } from "./constants/keybindings.js";
 function resolveTheme(mode) {
     if (mode === "system") {
         const detected = detectSystemTheme();
@@ -42,7 +43,7 @@ export const ThemeProvider = ({ initialTheme, children, }) => {
     }, []);
     // Ctrl+T to cycle theme
     useInput((input, key) => {
-        if (key.ctrl && input === "t") {
+        if (key.ctrl && input === KEYS.THEME_CYCLE) {
             cycleTheme();
         }
     });

package/dist/src/tui/components/ConfirmationDialog.js

@@ -3,6 +3,7 @@ import React, { useState } from "react";
 import { useTheme } from "../ThemeContext.js";
 import { SingleLineTextInput } from "./SingleLineTextInput.js";
 import { t } from "../../i18n/index.js";
+import { KEYS } from "../constants/keybindings.js";
 /**
  * ConfirmationDialog shows a 3-option prompt for session rejection
  * Options: Reject & inform AI, Cancel, or Quit CLI
@@ -37,20 +38,20 @@ export const ConfirmationDialog = ({ message, onReject, onCancel, onQuit, }) =>
         }
         // Arrow key navigation
         if (key.upArrow) {
-            setFocusedIndex((prev) => (prev > 0 ? prev - 1 : options.length - 1));
+            setFocusedIndex((prev) => Math.max(0, prev - 1));
         }
         if (key.downArrow) {
-            setFocusedIndex((prev) => (prev < options.length - 1 ? prev + 1 : 0));
+            setFocusedIndex((prev) => Math.min(options.length - 1, prev + 1));
         }
         // Enter key - select focused option
         if (key.return) {
             options[focusedIndex].action();
         }
         // Letter shortcuts
-        if (input === "y" || input === "Y") {
+        if (KEYS.CONFIRM_YES.test(input)) {
             setShowReasonInput(true);
         }
-        if (input === "n" || input === "N") {
+        if (KEYS.CONFIRM_NO.test(input)) {
             onCancel();
         }
         // Esc key - same as quit

package/dist/src/tui/components/Footer.js

@@ -2,6 +2,7 @@ import { Box, Text } from "ink";
 import React, { useEffect, useState } from "react";
 import { t } from "../../i18n/index.js";
 import { useTheme } from "../ThemeContext.js";
+import { KEY_LABELS } from "../constants/keybindings.js";
 const SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
 /**
  * Footer component - displays context-aware keybindings
@@ -23,58 +24,58 @@ export const Footer = ({ focusContext, multiSelect, isReviewScreen = false, show
         // Review screen mode
         if (isReviewScreen) {
             return [
-                { key: "Enter", action: t("footer.submit") },
-                { key: "n", action: t("footer.back") },
+                { key: KEY_LABELS.SUBMIT, action: t("footer.submit") },
+                { key: KEY_LABELS.BACK, action: t("footer.back") },
             ];
         }
         // Custom input focused
         if (focusContext === "custom-input") {
             return [
-                { key: "↑↓", action: t("footer.options") },
-                { key: "←→", action: t("footer.cursor") },
-                { key: "Tab/S+Tab", action: t("footer.questions") },
-                { key: "Enter", action: t("footer.newline") },
-                { key: "Esc", action: t("footer.reject") },
+                { key: KEY_LABELS.NAVIGATE_OPTIONS, action: t("footer.options") },
+                { key: KEY_LABELS.CURSOR, action: t("footer.cursor") },
+                { key: KEY_LABELS.NAVIGATE_QUESTIONS_TAB, action: t("footer.questions") },
+                { key: KEY_LABELS.NEWLINE, action: t("footer.newline") },
+                { key: KEY_LABELS.REJECT, action: t("footer.reject") },
             ];
         }
         // Elaborate input focused (Enter skips, not newline)
         if (focusContext === "elaborate-input") {
             return [
-                { key: "↑↓", action: t("footer.options") },
-                { key: "←→", action: t("footer.cursor") },
+                { key: KEY_LABELS.NAVIGATE_OPTIONS, action: t("footer.options") },
+                { key: KEY_LABELS.CURSOR, action: t("footer.cursor") },
                 { key: "Enter/Tab", action: t("footer.next") },
-                { key: "Esc", action: t("footer.reject") },
+                { key: KEY_LABELS.REJECT, action: t("footer.reject") },
             ];
         }
         // Option focused
         if (focusContext === "option") {
             const bindings = [
-                { key: "↑↓", action: t("footer.options") },
-                { key: "←→", action: t("footer.questions") },
-                { key: "Tab/S+Tab", action: t("footer.questions") },
+                { key: KEY_LABELS.NAVIGATE_OPTIONS, action: t("footer.options") },
+                { key: KEY_LABELS.NAVIGATE_QUESTIONS, action: t("footer.questions") },
+                { key: KEY_LABELS.NAVIGATE_QUESTIONS_TAB, action: t("footer.questions") },
             ];
             if (multiSelect) {
-                bindings.push({ key: "Space", action: t("footer.toggle") });
-                bindings.push({ key: "Enter", action: t("footer.next") });
+                bindings.push({ key: KEY_LABELS.SELECT, action: t("footer.toggle") });
+                bindings.push({ key: KEY_LABELS.NEXT, action: t("footer.next") });
             }
             else {
-                bindings.push({ key: "Space", action: t("footer.select") });
-                bindings.push({ key: "Enter", action: t("footer.selectNext") });
+                bindings.push({ key: KEY_LABELS.SELECT, action: t("footer.select") });
+                bindings.push({ key: KEY_LABELS.SELECT_NEXT, action: t("footer.selectNext") });
             }
             if (hasRecommendedOptions) {
-                bindings.push({ key: "R", action: t("footer.recommended") });
+                bindings.push({ key: KEY_LABELS.RECOMMEND, action: t("footer.recommended") });
             }
             // Ctrl+R shows when ANY question in session has recommended (not just current)
             if (hasAnyRecommendedInSession) {
-                bindings.push({ key: "Ctrl+R", action: t("footer.quickSubmit") });
+                bindings.push({ key: KEY_LABELS.QUICK_SUBMIT, action: t("footer.quickSubmit") });
             }
             if (showSessionSwitching) {
-                bindings.push({ key: "Ctrl+]/[", action: t("footer.sessions") });
+                bindings.push({ key: KEY_LABELS.SESSION_SWITCH, action: t("footer.sessions") });
                 bindings.push({ key: "1-9", action: t("footer.jump") });
-                bindings.push({ key: "Ctrl+S", action: t("footer.list") });
+                bindings.push({ key: KEY_LABELS.SESSION_LIST, action: t("footer.list") });
             }
-            bindings.push({ key: "Ctrl+T", action: t("footer.theme") });
-            bindings.push({ key: "Esc", action: t("footer.reject") });
+            bindings.push({ key: KEY_LABELS.THEME, action: t("footer.theme") });
+            bindings.push({ key: KEY_LABELS.REJECT, action: t("footer.reject") });
             return bindings;
         }
         return [];

package/dist/src/tui/components/ReviewScreen.js

@@ -4,6 +4,7 @@ import { t } from "../../i18n/index.js";
 import { useTheme } from "../ThemeContext.js";
 import { Footer } from "./Footer.js";
 import { MarkdownPrompt } from "./MarkdownPrompt.js";
+import { KEYS } from "../constants/keybindings.js";
 /**
  * ReviewScreen displays a summary of all answers for confirmation
  * User can press Enter to confirm and submit, or 'n' to go back and edit
@@ -32,7 +33,7 @@ export const ReviewScreen = ({ answers, elapsedLabel, onConfirm, onGoBack, quest
             });
             onConfirm(userAnswers);
         }
-        if (input === "n") {
+        if (KEYS.GO_BACK.test(input)) {
             onGoBack();
         }
     });

package/dist/src/tui/components/SessionPicker.js

@@ -2,6 +2,7 @@ import { Box, Text, useInput, useStdout } from "ink";
 import React, { useEffect, useState } from "react";
 import { useTheme } from "../ThemeContext.js";
 import { formatRelativeTime } from "../utils/relativeTime.js";
+import { KEYS } from "../constants/keybindings.js";
 /* ------------------------------------------------------------------ */
 /*  Helpers                                                           */
 /* ------------------------------------------------------------------ */
@@ -69,7 +70,7 @@ export const SessionPicker = ({ isOpen, sessions, activeIndex, sessionUIStates,
         else {
             // Direct number jump (1-9)
             const num = parseInt(input, 10);
-            if (num >= 1 && num <= sessions.length) {
+            if (num >= KEYS.SESSION_JUMP_MIN && num <= Math.min(KEYS.SESSION_JUMP_MAX, sessions.length)) {
                 onSelectIndex(num - 1);
                 onClose();
             }

package/dist/src/tui/components/StepperView.js

@@ -7,6 +7,7 @@ import { getSessionDirectory } from "../../session/utils.js";
 import { useTheme } from "../ThemeContext.js";
 import { useConfig } from "../ConfigContext.js";
 import { isRecommendedOption } from "../utils/recommended.js";
+import { KEYS } from "../constants/keybindings.js";
 import { ConfirmationDialog } from "./ConfirmationDialog.js";
 import { QuestionDisplay } from "./QuestionDisplay.js";
 import { ReviewScreen } from "./ReviewScreen.js";
@@ -358,7 +359,7 @@ export const StepperView = ({ onComplete, onProgress, hasMultipleSessions, initi
             return;
         }
         // Ctrl+R: Quick submit with recommended options (select all recommended and go to review)
-        if (input.toLowerCase() === "r" &&
+        if (input.toLowerCase() === KEYS.QUICK_SUBMIT &&
             key.ctrl &&
             hasAnyRecommendedInSession &&
             !isInTextInput) {
@@ -395,7 +396,7 @@ export const StepperView = ({ onComplete, onProgress, hasMultipleSessions, initi
             return;
         }
         // R key: Select recommended options for current question
-        if (input.toLowerCase() === "r" &&
+        if (input.toLowerCase() === KEYS.RECOMMEND &&
             !key.ctrl &&
             !isInTextInput &&
             hasRecommendedOptions) {

package/dist/src/tui/components/WaitingScreen.js

@@ -3,6 +3,7 @@ import React, { useEffect, useState } from "react";
 import { AnimatedGradient } from "./AnimatedGradient.js";
 import { useTheme } from "../ThemeContext.js";
 import { t } from "../../i18n/index.js";
+import { KEYS } from "../constants/keybindings.js";
 /**
  * WaitingScreen displays when no question sets are being processed
  * Shows "Waiting for AI..." message or queue status
@@ -22,7 +23,7 @@ export const WaitingScreen = ({ queueCount }) => {
     }, [startTime]);
     // Handle 'q' key to quit
     useInput((input, key) => {
-        if (input === "q") {
+        if (KEYS.QUIT.test(input)) {
             process.exit(0);
         }
     });

package/dist/src/tui/components/__tests__/ConfirmationDialog.test.js

@@ -0,0 +1,134 @@
+import React from "react";
+import { cleanup, render } from "ink-testing-library";
+import { afterEach, describe, expect, it, vi } from "vitest";
+const inputState = vi.hoisted(() => ({
+    handler: null,
+}));
+vi.mock("ink", async () => {
+    const actual = await vi.importActual("ink");
+    return {
+        ...actual,
+        useInput: (handler, options) => {
+            // ConfirmationDialog calls useInput without options, so always capture
+            if (!options || options.isActive !== false) {
+                inputState.handler = handler;
+            }
+        },
+    };
+});
+import { ThemeContext } from "../../ThemeContext.js";
+import { darkTheme } from "../../themes/dark.js";
+import { ConfirmationDialog } from "../ConfirmationDialog.js";
+const mockThemeValue = {
+    theme: darkTheme,
+    themeName: "AUQ dark",
+    cycleTheme: () => { },
+};
+function renderWithTheme(ui) {
+    return render(React.createElement(ThemeContext.Provider, { value: mockThemeValue }, ui));
+}
+afterEach(() => {
+    cleanup();
+    inputState.handler = null;
+    vi.restoreAllMocks();
+});
+describe("ConfirmationDialog keyboard handling", () => {
+    const defaultProps = {
+        message: "Test confirmation",
+        onReject: vi.fn(),
+        onCancel: vi.fn(),
+        onQuit: vi.fn(),
+    };
+    function renderDialog(overrides = {}) {
+        const props = {
+            ...defaultProps,
+            onReject: vi.fn(),
+            onCancel: vi.fn(),
+            onQuit: vi.fn(),
+            ...overrides,
+        };
+        const instance = renderWithTheme(React.createElement(ConfirmationDialog, { ...props }));
+        return { instance, ...props };
+    }
+    it("arrow down at last item stays at last item (clamping)", async () => {
+        const { onCancel, instance } = renderDialog();
+        expect(inputState.handler).not.toBeNull();
+        // There are 2 options (index 0 and 1). Press down to go to last.
+        inputState.handler("", { downArrow: true });
+        await new Promise((r) => setTimeout(r, 50));
+        // Press down again — should clamp at last item, not wrap to first
+        inputState.handler("", { downArrow: true });
+        await new Promise((r) => setTimeout(r, 50));
+        // Press down a third time — still clamped at last
+        inputState.handler("", { downArrow: true });
+        await new Promise((r) => setTimeout(r, 50));
+        // Now press Enter — should select the last option (index 1 = onCancel)
+        inputState.handler("", { return: true });
+        await new Promise((r) => setTimeout(r, 50));
+        // The second option's action is onCancel
+        expect(onCancel).toHaveBeenCalled();
+    });
+    it("arrow up at first item stays at first item (clamping)", async () => {
+        const { onCancel } = renderDialog();
+        expect(inputState.handler).not.toBeNull();
+        // At index 0, press up multiple times
+        inputState.handler("", { upArrow: true });
+        await Promise.resolve();
+        inputState.handler("", { upArrow: true });
+        await Promise.resolve();
+        // Press Enter — should select first option (index 0 = setShowReasonInput)
+        // The first option's action is setShowReasonInput(true), not onCancel
+        inputState.handler("", { return: true });
+        await Promise.resolve();
+        // onCancel should NOT have been called (that's the second option)
+        expect(onCancel).not.toHaveBeenCalled();
+    });
+    it("Enter selects focused option", async () => {
+        const { onCancel } = renderDialog();
+        expect(inputState.handler).not.toBeNull();
+        // Default focus is index 0 (Yes option). Press Enter.
+        inputState.handler("", { return: true });
+        await Promise.resolve();
+        // First option sets showReasonInput=true, does NOT call onCancel
+        expect(onCancel).not.toHaveBeenCalled();
+    });
+    it("y key triggers yes action", async () => {
+        renderDialog();
+        expect(inputState.handler).not.toBeNull();
+        // Press 'y' — should trigger CONFIRM_YES shortcut (setShowReasonInput)
+        inputState.handler("y", {});
+        await Promise.resolve();
+        // After pressing y, the component transitions to reason input mode
+        // We verify it didn't call onCancel or onQuit
+        // (The actual transition to reason input is internal state)
+    });
+    it("Y key (uppercase) triggers yes action (case-insensitive)", async () => {
+        renderDialog();
+        expect(inputState.handler).not.toBeNull();
+        // Press 'Y' — KEYS.CONFIRM_YES is /^[yY]$/, should match
+        inputState.handler("Y", {});
+        await Promise.resolve();
+        // Should work same as lowercase 'y'
+    });
+    it("n key triggers cancel action", async () => {
+        const { onCancel } = renderDialog();
+        expect(inputState.handler).not.toBeNull();
+        inputState.handler("n", {});
+        await Promise.resolve();
+        expect(onCancel).toHaveBeenCalled();
+    });
+    it("N key (uppercase) triggers cancel action (case-insensitive)", async () => {
+        const { onCancel } = renderDialog();
+        expect(inputState.handler).not.toBeNull();
+        inputState.handler("N", {});
+        await Promise.resolve();
+        expect(onCancel).toHaveBeenCalled();
+    });
+    it("Escape triggers quit", async () => {
+        const { onQuit } = renderDialog();
+        expect(inputState.handler).not.toBeNull();
+        inputState.handler("", { escape: true });
+        await Promise.resolve();
+        expect(onQuit).toHaveBeenCalled();
+    });
+});

package/dist/src/tui/components/__tests__/Footer.test.js

@@ -0,0 +1,121 @@
+import React from "react";
+import { cleanup, render } from "ink-testing-library";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { ThemeContext } from "../../ThemeContext.js";
+import { darkTheme } from "../../themes/dark.js";
+import { KEY_LABELS } from "../../constants/keybindings.js";
+import { Footer } from "../Footer.js";
+const mockThemeValue = {
+    theme: darkTheme,
+    themeName: "AUQ dark",
+    cycleTheme: () => { },
+};
+function renderWithTheme(ui) {
+    return render(React.createElement(ThemeContext.Provider, { value: mockThemeValue }, ui));
+}
+function getOutput(frame) {
+    return (frame ?? "").replace(/\x1b\[[0-9;]*m/g, "").replace(/\r/g, "");
+}
+afterEach(() => {
+    cleanup();
+    vi.restoreAllMocks();
+});
+describe("Footer keybinding labels", () => {
+    it("option context (single-select) shows correct keybindings", () => {
+        const instance = renderWithTheme(React.createElement(Footer, { focusContext: "option", multiSelect: false }));
+        const output = getOutput(instance.lastFrame());
+        expect(output).toContain(KEY_LABELS.SELECT); // "Space"
+        expect(output).toContain(KEY_LABELS.SELECT_NEXT); // "Enter"
+        expect(output).toContain(KEY_LABELS.REJECT); // "Esc"
+        expect(output).toContain(KEY_LABELS.NAVIGATE_OPTIONS); // "↑↓"
+        expect(output).toContain(KEY_LABELS.NAVIGATE_QUESTIONS); // "←→"
+    });
+    it("option context (multi-select) shows Toggle label", () => {
+        const instance = renderWithTheme(React.createElement(Footer, { focusContext: "option", multiSelect: true }));
+        const output = getOutput(instance.lastFrame());
+        expect(output).toContain("Toggle");
+        expect(output).toContain(KEY_LABELS.SELECT); // "Space"
+        expect(output).toContain(KEY_LABELS.NEXT); // "Enter"
+    });
+    it("custom-input context shows correct keybindings", () => {
+        const instance = renderWithTheme(React.createElement(Footer, { focusContext: "custom-input", multiSelect: false }));
+        const output = getOutput(instance.lastFrame());
+        expect(output).toContain(KEY_LABELS.NAVIGATE_OPTIONS); // "↑↓"
+        expect(output).toContain(KEY_LABELS.CURSOR); // "←→"
+        expect(output).toContain(KEY_LABELS.NAVIGATE_QUESTIONS_TAB); // "Tab/S+Tab"
+        expect(output).toContain(KEY_LABELS.NEWLINE); // "Enter"
+        expect(output).toContain(KEY_LABELS.REJECT); // "Esc"
+    });
+    it("elaborate-input context shows correct keybindings", () => {
+        const instance = renderWithTheme(React.createElement(Footer, { focusContext: "elaborate-input", multiSelect: false }));
+        const output = getOutput(instance.lastFrame());
+        expect(output).toContain(KEY_LABELS.NAVIGATE_OPTIONS); // "↑↓"
+        expect(output).toContain(KEY_LABELS.CURSOR); // "←→"
+        expect(output).toContain("Enter/Tab");
+        expect(output).toContain(KEY_LABELS.REJECT); // "Esc"
+    });
+    it("review screen shows Submit and Back labels", () => {
+        const instance = renderWithTheme(React.createElement(Footer, { focusContext: "option", multiSelect: false, isReviewScreen: true }));
+        const output = getOutput(instance.lastFrame());
+        expect(output).toContain(KEY_LABELS.SUBMIT); // "Enter"
+        expect(output).toContain(KEY_LABELS.BACK); // "n"
+        expect(output).toContain("Submit");
+        expect(output).toContain("Back");
+    });
+    it("session switch shows ]/[ (not Ctrl+]/[)", () => {
+        const instance = renderWithTheme(React.createElement(Footer, { focusContext: "option", multiSelect: false, showSessionSwitching: true }));
+        const output = getOutput(instance.lastFrame());
+        // Should show "]/ [" session label
+        expect(output).toContain(KEY_LABELS.SESSION_SWITCH); // "]/["
+        // Must NOT contain Ctrl+] or Ctrl+[ anywhere
+        expect(output).not.toContain("Ctrl+]");
+        expect(output).not.toContain("Ctrl+[");
+    });
+    it("recommended key shown when hasRecommendedOptions is true", () => {
+        const instance = renderWithTheme(React.createElement(Footer, { focusContext: "option", multiSelect: false, hasRecommendedOptions: true }));
+        const output = getOutput(instance.lastFrame());
+        expect(output).toContain(KEY_LABELS.RECOMMEND); // "R"
+        expect(output).toContain("Recommended");
+    });
+    it("recommended key NOT shown when hasRecommendedOptions is false", () => {
+        const instance = renderWithTheme(React.createElement(Footer, { focusContext: "option", multiSelect: false, hasRecommendedOptions: false }));
+        const output = getOutput(instance.lastFrame());
+        expect(output).not.toContain("Recommended");
+    });
+    it("quick submit shown when hasAnyRecommendedInSession is true", () => {
+        const instance = renderWithTheme(React.createElement(Footer, { focusContext: "option", multiSelect: false, hasAnyRecommendedInSession: true }));
+        const output = getOutput(instance.lastFrame());
+        expect(output).toContain(KEY_LABELS.QUICK_SUBMIT); // "Ctrl+R"
+        expect(output).toContain("Quick Submit");
+    });
+    it("quick submit NOT shown when hasAnyRecommendedInSession is false", () => {
+        const instance = renderWithTheme(React.createElement(Footer, { focusContext: "option", multiSelect: false, hasAnyRecommendedInSession: false }));
+        const output = getOutput(instance.lastFrame());
+        expect(output).not.toContain("Quick Submit");
+    });
+    it("session switching shows 1-9 jump and Ctrl+S list labels", () => {
+        const instance = renderWithTheme(React.createElement(Footer, { focusContext: "option", multiSelect: false, showSessionSwitching: true }));
+        const output = getOutput(instance.lastFrame());
+        expect(output).toContain("1-9");
+        expect(output).toContain("Jump");
+        expect(output).toContain(KEY_LABELS.SESSION_LIST); // "Ctrl+S"
+        expect(output).toContain("List");
+    });
+    it("theme toggle is always shown in option context", () => {
+        const instance = renderWithTheme(React.createElement(Footer, { focusContext: "option", multiSelect: false }));
+        const output = getOutput(instance.lastFrame());
+        expect(output).toContain(KEY_LABELS.THEME); // "Ctrl+T"
+        expect(output).toContain("Theme");
+    });
+    it("review screen shows only submit and back, not option keybindings", () => {
+        const instance = renderWithTheme(React.createElement(Footer, { focusContext: "option", multiSelect: false, isReviewScreen: true }));
+        const output = getOutput(instance.lastFrame());
+        // Review screen should only show Submit and Back
+        expect(output).toContain("Submit");
+        expect(output).toContain("Back");
+        // Should NOT contain option-context keybindings
+        expect(output).not.toContain("Toggle");
+        expect(output).not.toContain("Theme");
+        expect(output).not.toContain("Questions");
+    });
+});

package/dist/src/tui/components/__tests__/ReviewScreen.test.js

@@ -0,0 +1,89 @@
+import React from "react";
+import { cleanup, render } from "ink-testing-library";
+import { afterEach, describe, expect, it, vi } from "vitest";
+const inputState = vi.hoisted(() => ({
+    handler: null,
+}));
+vi.mock("ink", async () => {
+    const actual = await vi.importActual("ink");
+    return {
+        ...actual,
+        useInput: (handler, options) => {
+            // ReviewScreen calls useInput without options, so always capture
+            if (!options || options.isActive !== false) {
+                inputState.handler = handler;
+            }
+        },
+    };
+});
+import { ThemeContext } from "../../ThemeContext.js";
+import { darkTheme } from "../../themes/dark.js";
+import { ReviewScreen } from "../ReviewScreen.js";
+const mockThemeValue = {
+    theme: darkTheme,
+    themeName: "AUQ dark",
+    cycleTheme: () => { },
+};
+function renderWithTheme(ui) {
+    return render(React.createElement(ThemeContext.Provider, { value: mockThemeValue }, ui));
+}
+afterEach(() => {
+    cleanup();
+    inputState.handler = null;
+    vi.restoreAllMocks();
+});
+describe("ReviewScreen keyboard handling", () => {
+    const sampleQuestions = [
+        {
+            title: "Q1",
+            prompt: "Choose an option",
+            options: [{ label: "Option A" }, { label: "Option B" }],
+            multiSelect: false,
+        },
+    ];
+    const sampleAnswers = new Map([
+        [0, { selectedOption: "Option A" }],
+    ]);
+    function renderReview(overrides = {}) {
+        const props = {
+            questions: sampleQuestions,
+            answers: sampleAnswers,
+            elapsedLabel: "5s",
+            sessionId: "test-session-1",
+            onConfirm: vi.fn(),
+            onGoBack: vi.fn(),
+            isSubmitting: false,
+            ...overrides,
+        };
+        const instance = renderWithTheme(React.createElement(ReviewScreen, { ...props }));
+        return { instance, ...props };
+    }
+    it("Enter submits answers", async () => {
+        const { onConfirm } = renderReview();
+        expect(inputState.handler).not.toBeNull();
+        inputState.handler("", { return: true });
+        await Promise.resolve();
+        expect(onConfirm).toHaveBeenCalledTimes(1);
+    });
+    it("n key goes back", async () => {
+        const { onGoBack } = renderReview();
+        expect(inputState.handler).not.toBeNull();
+        inputState.handler("n", {});
+        await Promise.resolve();
+        expect(onGoBack).toHaveBeenCalledTimes(1);
+    });
+    it("N key (uppercase) goes back (case-insensitive)", async () => {
+        const { onGoBack } = renderReview();
+        expect(inputState.handler).not.toBeNull();
+        inputState.handler("N", {});
+        await Promise.resolve();
+        expect(onGoBack).toHaveBeenCalledTimes(1);
+    });
+    it("Enter does not fire while submitting", async () => {
+        const { onConfirm } = renderReview({ isSubmitting: true });
+        expect(inputState.handler).not.toBeNull();
+        inputState.handler("", { return: true });
+        await Promise.resolve();
+        expect(onConfirm).not.toHaveBeenCalled();
+    });
+});

package/dist/src/tui/components/__tests__/StepperView.keyboard.test.js

@@ -0,0 +1,135 @@
+import React from "react";
+import { cleanup, render } from "ink-testing-library";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { ConfigProvider } from "../../ConfigContext.js";
+import { ThemeContext } from "../../ThemeContext.js";
+import { darkTheme } from "../../themes/dark.js";
+import { StepperView } from "../StepperView.js";
+const mockThemeValue = {
+    theme: darkTheme,
+    themeName: "AUQ dark",
+    cycleTheme: () => { },
+};
+const sessionRequest = {
+    sessionId: "kbd-test-session",
+    status: "pending",
+    timestamp: new Date().toISOString(),
+    callId: "call-kbd-1",
+    questions: [
+        {
+            title: "Q1",
+            prompt: "First question?",
+            options: [{ label: "A" }, { label: "B" }],
+            multiSelect: false,
+        },
+        {
+            title: "Q2",
+            prompt: "Second question?",
+            options: [{ label: "C" }, { label: "D" }],
+            multiSelect: false,
+        },
+        {
+            title: "Q3",
+            prompt: "Third question?",
+            options: [{ label: "E" }, { label: "F" }],
+            multiSelect: false,
+        },
+    ],
+};
+function renderStepper(props = {}) {
+    return render(React.createElement(ThemeContext.Provider, { value: mockThemeValue },
+        React.createElement(ConfigProvider, null,
+            React.createElement(StepperView, { sessionId: sessionRequest.sessionId, sessionRequest: sessionRequest, ...props }))));
+}
+function getOutput(frame) {
+    return (frame ?? "").replace(/\x1b\[[0-9;]*m/g, "").replace(/\r/g, "");
+}
+afterEach(() => {
+    cleanup();
+    vi.restoreAllMocks();
+});
+describe("StepperView keyboard shortcuts", () => {
+    it("Escape shows rejection confirmation dialog", async () => {
+        const instance = renderStepper();
+        // Verify we start on question 1
+        let output = getOutput(instance.lastFrame());
+        expect(output).toContain("First question?");
+        // Press Escape
+        instance.stdin.write("\x1b");
+        await vi.waitFor(() => {
+            const out = getOutput(instance.lastFrame());
+            expect(out).toContain("Reject");
+        });
+    });
+    it("Tab navigates to next question", async () => {
+        const instance = renderStepper();
+        // Verify starting on question 1
+        let output = getOutput(instance.lastFrame());
+        expect(output).toContain("First question?");
+        // Press Tab to advance to Q2
+        instance.stdin.write("\t");
+        await vi.waitFor(() => {
+            const out = getOutput(instance.lastFrame());
+            expect(out).toContain("Second question?");
+        });
+    });
+    it("Shift+Tab navigates to previous question", async () => {
+        const onStateSnapshot = vi.fn();
+        const instance = renderStepper({ onStateSnapshot });
+        // First advance to Q2 with Tab
+        instance.stdin.write("\t");
+        await vi.waitFor(() => {
+            const out = getOutput(instance.lastFrame());
+            expect(out).toContain("Second question?");
+        });
+        // Press Shift+Tab (escape sequence for shift-tab in ink)
+        instance.stdin.write("\x1b[Z");
+        await vi.waitFor(() => {
+            const out = getOutput(instance.lastFrame());
+            expect(out).toContain("First question?");
+        });
+    });
+    it("Tab does not navigate past the last question", async () => {
+        const instance = renderStepper();
+        // Navigate to Q3 (last question)
+        instance.stdin.write("\t"); // Q1 -> Q2
+        await vi.waitFor(() => {
+            const out = getOutput(instance.lastFrame());
+            expect(out).toContain("Second question?");
+        });
+        instance.stdin.write("\t"); // Q2 -> Q3
+        await vi.waitFor(() => {
+            const out = getOutput(instance.lastFrame());
+            expect(out).toContain("Third question?");
+        });
+        // Tab again should stay on Q3 (clamped)
+        instance.stdin.write("\t");
+        await vi.waitFor(() => {
+            const out = getOutput(instance.lastFrame());
+            expect(out).toContain("Third question?");
+        });
+    });
+    it("Shift+Tab does not navigate before the first question", async () => {
+        const instance = renderStepper();
+        // Verify on Q1
+        let output = getOutput(instance.lastFrame());
+        expect(output).toContain("First question?");
+        // Press Shift+Tab at Q1 — should remain on Q1
+        instance.stdin.write("\x1b[Z");
+        // Allow state to settle
+        await vi.waitFor(() => {
+            const out = getOutput(instance.lastFrame());
+            expect(out).toContain("First question?");
+        });
+    });
+    it("emits onProgress when Tab advances question", async () => {
+        const onProgress = vi.fn();
+        const instance = renderStepper({ onProgress });
+        // Tab to advance from Q1 to Q2
+        instance.stdin.write("\t");
+        await vi.waitFor(() => {
+            // onProgress should be called with (answered=1, total=3)
+            expect(onProgress).toHaveBeenCalledWith(1, 3);
+        });
+    });
+});

package/dist/src/tui/components/__tests__/WaitingScreen.test.js

@@ -0,0 +1,60 @@
+import React from "react";
+import { cleanup, render } from "ink-testing-library";
+import { afterEach, describe, expect, it, vi } from "vitest";
+const inputState = vi.hoisted(() => ({
+    handler: null,
+}));
+vi.mock("ink", async () => {
+    const actual = await vi.importActual("ink");
+    return {
+        ...actual,
+        useInput: (handler, options) => {
+            // WaitingScreen calls useInput without options, so always capture
+            if (!options || options.isActive !== false) {
+                inputState.handler = handler;
+            }
+        },
+    };
+});
+// Mock AnimatedGradient to avoid timer/animation side effects
+vi.mock("../AnimatedGradient.js", () => ({
+    AnimatedGradient: ({ text }) => React.createElement("ink-text", null, text),
+}));
+import { ThemeContext } from "../../ThemeContext.js";
+import { darkTheme } from "../../themes/dark.js";
+import { WaitingScreen } from "../WaitingScreen.js";
+const mockThemeValue = {
+    theme: darkTheme,
+    themeName: "AUQ dark",
+    cycleTheme: () => { },
+};
+function renderWithTheme(ui) {
+    return render(React.createElement(ThemeContext.Provider, { value: mockThemeValue }, ui));
+}
+afterEach(() => {
+    cleanup();
+    inputState.handler = null;
+    vi.restoreAllMocks();
+});
+describe("WaitingScreen keyboard handling", () => {
+    it("q key triggers quit", async () => {
+        const exitSpy = vi
+            .spyOn(process, "exit")
+            .mockImplementation((() => { }));
+        renderWithTheme(React.createElement(WaitingScreen, { queueCount: 0 }));
+        expect(inputState.handler).not.toBeNull();
+        inputState.handler("q", {});
+        await Promise.resolve();
+        expect(exitSpy).toHaveBeenCalledWith(0);
+    });
+    it("Q key (uppercase) triggers quit (case-insensitive)", async () => {
+        const exitSpy = vi
+            .spyOn(process, "exit")
+            .mockImplementation((() => { }));
+        renderWithTheme(React.createElement(WaitingScreen, { queueCount: 0 }));
+        expect(inputState.handler).not.toBeNull();
+        inputState.handler("Q", {});
+        await Promise.resolve();
+        expect(exitSpy).toHaveBeenCalledWith(0);
+    });
+});

package/dist/src/tui/constants/keybindings.js

@@ -0,0 +1,40 @@
+// Keybinding constants for the TUI application
+// All keyboard shortcut definitions are centralized here.
+export const KEYS = {
+    // Session switching (bare keys, no Ctrl)
+    SESSION_NEXT: "]",
+    SESSION_PREV: "[",
+    SESSION_JUMP_MIN: 1,
+    SESSION_JUMP_MAX: 9,
+    // Question navigation
+    RECOMMEND: "r",
+    QUICK_SUBMIT: "r", // used with key.ctrl
+    // Theme
+    THEME_CYCLE: "t", // used with key.ctrl
+    // Confirmation shortcuts
+    CONFIRM_YES: /^[yY]$/,
+    CONFIRM_NO: /^[nN]$/,
+    // Review
+    GO_BACK: /^[nN]$/,
+    // Waiting
+    QUIT: /^[qQ]$/,
+};
+// Display labels for Footer keybinding hints
+export const KEY_LABELS = {
+    SESSION_SWITCH: "]/[",
+    SESSION_LIST: "Ctrl+S",
+    QUICK_SUBMIT: "Ctrl+R",
+    RECOMMEND: "R",
+    THEME: "Ctrl+T",
+    NAVIGATE_QUESTIONS: "←→",
+    NAVIGATE_QUESTIONS_TAB: "Tab/S+Tab",
+    NAVIGATE_OPTIONS: "↑↓",
+    SELECT: "Space",
+    SELECT_NEXT: "Enter",
+    NEXT: "Enter",
+    CURSOR: "←→",
+    NEWLINE: "Enter",
+    REJECT: "Esc",
+    BACK: "n",
+    SUBMIT: "Enter",
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "auq-mcp-server",
-  "version": "2.2.2",
+  "version": "2.3.0",
   "main": "dist/index.js",
   "bin": {
     "auq": "dist/bin/auq.js"