auq-mcp-server 2.6.3 → 2.7.0

package/dist/src/cli/commands/__tests__/fetch-answers.test.js

@@ -0,0 +1,310 @@
+/**
+ * Integration tests for the `auq fetch-answers` CLI command.
+ */
+import { promises as fs } from "fs";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { SessionManager } from "../../../session/SessionManager.js";
+import { runFetchAnswersCommand } from "../fetch-answers.js";
+// ── Helpers ────────────────────────────────────────────────────────────────
+const testBaseDir = "/tmp/auq-test-cli-fetch-answers";
+const sampleQuestions = [
+    {
+        title: "Language",
+        prompt: "Which language do you prefer?",
+        options: [
+            { label: "TypeScript", description: "Typed JS" },
+            { label: "Python", description: "Scripting" },
+        ],
+    },
+    {
+        title: "Framework",
+        prompt: "Pick a framework",
+        options: [
+            { label: "React" },
+            { label: "Vue" },
+        ],
+    },
+];
+// Stub getSessionDirectory so the fetch-answers command always targets our temp dir.
+vi.mock("../../../session/utils.js", async (importOriginal) => {
+    const actual = (await importOriginal());
+    return {
+        ...actual,
+        getSessionDirectory: () => testBaseDir,
+    };
+});
+/**
+ * Helper: create a completed session with answers saved.
+ */
+async function createCompletedSession(sessionManager, questions = sampleQuestions) {
+    const sessionId = await sessionManager.createSession(questions);
+    const answersData = {
+        sessionId,
+        timestamp: new Date().toISOString(),
+        answers: questions.map((q, i) => ({
+            questionIndex: i,
+            timestamp: new Date().toISOString(),
+            selectedOption: q.options[0].label,
+        })),
+    };
+    await sessionManager.saveSessionAnswers(sessionId, answersData);
+    await sessionManager.updateSessionStatus(sessionId, "completed");
+    return sessionId;
+}
+// ── Test Suite ─────────────────────────────────────────────────────────────
+describe("fetch-answers command", () => {
+    let sessionManager;
+    let consoleLogSpy;
+    let consoleErrorSpy;
+    beforeEach(async () => {
+        await fs.rm(testBaseDir, { force: true, recursive: true }).catch(() => { });
+        sessionManager = new SessionManager({ baseDir: testBaseDir });
+        await sessionManager.initialize();
+        process.exitCode = undefined;
+        consoleLogSpy = vi.spyOn(console, "log").mockImplementation(() => { });
+        consoleErrorSpy = vi.spyOn(console, "error").mockImplementation(() => { });
+    });
+    afterEach(async () => {
+        consoleLogSpy.mockRestore();
+        consoleErrorSpy.mockRestore();
+        vi.restoreAllMocks();
+        process.exitCode = undefined;
+        await fs.rm(testBaseDir, { force: true, recursive: true }).catch(() => { });
+    });
+    // ── Fetch specific session ──────────────────────────────────────────────
+    describe("fetch specific session", () => {
+        it("should display formatted answers for completed session", async () => {
+            const sessionId = await createCompletedSession(sessionManager);
+            await runFetchAnswersCommand([sessionId]);
+            expect(process.exitCode).toBeUndefined();
+            const allOutput = consoleLogSpy.mock.calls.map((c) => c[0]).join("\n");
+            // Should contain answer content from the session
+            expect(allOutput).toBeTruthy();
+            expect(allOutput.length).toBeGreaterThan(0);
+        });
+        it("should mark session as read after fetching", async () => {
+            const sessionId = await createCompletedSession(sessionManager);
+            // Should not be in unread before fetching (actually it IS unread)
+            const unreadBefore = await sessionManager.getUnreadSessions();
+            expect(unreadBefore).toContain(sessionId);
+            await runFetchAnswersCommand([sessionId]);
+            // After fetching, session should be marked as read
+            const unreadAfter = await sessionManager.getUnreadSessions();
+            expect(unreadAfter).not.toContain(sessionId);
+        });
+        it("should display pending status for pending session (non-blocking)", async () => {
+            const sessionId = await sessionManager.createSession(sampleQuestions);
+            await runFetchAnswersCommand([sessionId]);
+            expect(process.exitCode).toBeUndefined();
+            const allOutput = consoleLogSpy.mock.calls.map((c) => c[0]).join("\n");
+            // Should contain some output (pending status)
+            expect(allOutput).toBeTruthy();
+        });
+        it("should display rejected status", async () => {
+            const sessionId = await sessionManager.createSession(sampleQuestions);
+            await sessionManager.updateSessionStatus(sessionId, "rejected");
+            await runFetchAnswersCommand([sessionId]);
+            expect(process.exitCode).toBeUndefined();
+            const allOutput = consoleLogSpy.mock.calls.map((c) => c[0]).join("\n");
+            expect(allOutput).toBeTruthy();
+        });
+        it("should resolve short session ID (8-char prefix)", async () => {
+            const sessionId = await createCompletedSession(sessionManager);
+            const shortId = sessionId.slice(0, 8);
+            await runFetchAnswersCommand([shortId]);
+            expect(process.exitCode).toBeUndefined();
+            const allOutput = consoleLogSpy.mock.calls.map((c) => c[0]).join("\n");
+            expect(allOutput).toBeTruthy();
+        });
+        it("should error for non-existent full-UUID session", async () => {
+            const fakeId = "00000000-0000-4000-a000-000000000000";
+            await runFetchAnswersCommand([fakeId]);
+            expect(process.exitCode).toBe(1);
+            const errOutput = consoleErrorSpy.mock.calls.map((c) => c[0]).join("\n");
+            const logOutput = consoleLogSpy.mock.calls.map((c) => c[0]).join("\n");
+            const combined = errOutput + logOutput;
+            expect(combined).toContain(fakeId);
+        });
+        it("should error for non-existent 8-char prefix", async () => {
+            const fakeShortId = "deadbeef";
+            await runFetchAnswersCommand([fakeShortId]);
+            expect(process.exitCode).toBe(1);
+        });
+    });
+    // ── --json flag ─────────────────────────────────────────────────────────
+    describe("--json flag", () => {
+        it("should output valid JSON for completed session", async () => {
+            const sessionId = await createCompletedSession(sessionManager);
+            await runFetchAnswersCommand([sessionId, "--json"]);
+            expect(process.exitCode).toBeUndefined();
+            // Find valid JSON in console.log calls
+            const jsonCalls = consoleLogSpy.mock.calls.filter((c) => {
+                try {
+                    JSON.parse(c[0]);
+                    return true;
+                }
+                catch {
+                    return false;
+                }
+            });
+            expect(jsonCalls.length).toBeGreaterThanOrEqual(1);
+            const parsed = JSON.parse(jsonCalls[0][0]);
+            expect(parsed.sessionId).toBe(sessionId);
+            expect(parsed.status).toBe("completed");
+            expect(Array.isArray(parsed.answers)).toBe(true);
+            expect(parsed.answers).toHaveLength(2);
+            expect(parsed.lastReadAt).toBeDefined();
+        });
+        it("should output valid JSON for pending session", async () => {
+            const sessionId = await sessionManager.createSession(sampleQuestions);
+            await runFetchAnswersCommand([sessionId, "--json"]);
+            const jsonCalls = consoleLogSpy.mock.calls.filter((c) => {
+                try {
+                    JSON.parse(c[0]);
+                    return true;
+                }
+                catch {
+                    return false;
+                }
+            });
+            expect(jsonCalls.length).toBeGreaterThanOrEqual(1);
+            const parsed = JSON.parse(jsonCalls[0][0]);
+            expect(parsed.sessionId).toBe(sessionId);
+            expect(parsed.status).toBe("pending");
+            expect(parsed.answers).toBeNull();
+        });
+        it("should output valid JSON for rejected session", async () => {
+            const sessionId = await sessionManager.createSession(sampleQuestions);
+            await sessionManager.updateSessionStatus(sessionId, "rejected");
+            await runFetchAnswersCommand([sessionId, "--json"]);
+            const jsonCalls = consoleLogSpy.mock.calls.filter((c) => {
+                try {
+                    JSON.parse(c[0]);
+                    return true;
+                }
+                catch {
+                    return false;
+                }
+            });
+            expect(jsonCalls.length).toBeGreaterThanOrEqual(1);
+            const parsed = JSON.parse(jsonCalls[0][0]);
+            expect(parsed.sessionId).toBe(sessionId);
+            expect(parsed.status).toBe("rejected");
+        });
+    });
+    // ── Unread / no session-id mode ─────────────────────────────────────────
+    describe("unread / default mode (no session-id)", () => {
+        it("should list unread sessions when no session-id provided", async () => {
+            const id1 = await createCompletedSession(sessionManager);
+            const id2 = await createCompletedSession(sessionManager);
+            await runFetchAnswersCommand([]);
+            expect(process.exitCode).toBeUndefined();
+            const allOutput = consoleLogSpy.mock.calls.map((c) => c[0]).join("\n");
+            expect(allOutput).toContain(id1.slice(0, 8));
+            expect(allOutput).toContain(id2.slice(0, 8));
+        });
+        it("should show message when no unread sessions", async () => {
+            await runFetchAnswersCommand([]);
+            expect(process.exitCode).toBeUndefined();
+            const allOutput = consoleLogSpy.mock.calls.map((c) => c[0]).join("\n");
+            expect(allOutput.toLowerCase()).toContain("no unread");
+        });
+        it("should exclude already-read sessions from default unread list", async () => {
+            const sessionId = await createCompletedSession(sessionManager);
+            // Mark as read first
+            await sessionManager.markSessionAsRead(sessionId);
+            await runFetchAnswersCommand([]);
+            const allOutput = consoleLogSpy.mock.calls.map((c) => c[0]).join("\n");
+            // Session should NOT appear in unread list
+            expect(allOutput).not.toContain(sessionId.slice(0, 8));
+        });
+        it("should list unread sessions with explicit --unread flag", async () => {
+            const sessionId = await createCompletedSession(sessionManager);
+            await runFetchAnswersCommand(["--unread"]);
+            expect(process.exitCode).toBeUndefined();
+            const allOutput = consoleLogSpy.mock.calls.map((c) => c[0]).join("\n");
+            expect(allOutput).toContain(sessionId.slice(0, 8));
+        });
+        it("should output valid JSON array for unread list with --json", async () => {
+            const id1 = await createCompletedSession(sessionManager);
+            const id2 = await createCompletedSession(sessionManager);
+            await runFetchAnswersCommand(["--json"]);
+            expect(process.exitCode).toBeUndefined();
+            const jsonCalls = consoleLogSpy.mock.calls.filter((c) => {
+                try {
+                    JSON.parse(c[0]);
+                    return true;
+                }
+                catch {
+                    return false;
+                }
+            });
+            expect(jsonCalls.length).toBeGreaterThanOrEqual(1);
+            const parsed = JSON.parse(jsonCalls[0][0]);
+            expect(Array.isArray(parsed)).toBe(true);
+            expect(parsed.length).toBe(2);
+            // Both session IDs appear in result
+            const ids = parsed.map((e) => e.sessionId);
+            expect(ids).toContain(id1);
+            expect(ids).toContain(id2);
+        });
+        it("should output empty JSON array when no unread sessions with --json", async () => {
+            await runFetchAnswersCommand(["--json"]);
+            const jsonCalls = consoleLogSpy.mock.calls.filter((c) => {
+                try {
+                    JSON.parse(c[0]);
+                    return true;
+                }
+                catch {
+                    return false;
+                }
+            });
+            expect(jsonCalls.length).toBeGreaterThanOrEqual(1);
+            const parsed = JSON.parse(jsonCalls[0][0]);
+            expect(Array.isArray(parsed)).toBe(true);
+            expect(parsed.length).toBe(0);
+        });
+    });
+    // ── --blocking with no session id ───────────────────────────────────────
+    describe("--blocking flag validation", () => {
+        it("should error when --blocking used without a session ID", async () => {
+            await runFetchAnswersCommand(["--blocking"]);
+            expect(process.exitCode).toBe(1);
+            // Should have some error output (either console.error or console.log JSON error)
+            const logOutput = consoleLogSpy.mock.calls.map((c) => c[0]).join("\n");
+            const errOutput = consoleErrorSpy.mock.calls.map((c) => c[0]).join("\n");
+            const combined = logOutput + errOutput;
+            expect(combined.toLowerCase()).toMatch(/blocking|session id/i);
+        });
+    });
+    // ── lastReadAt tracking ─────────────────────────────────────────────────
+    describe("read tracking", () => {
+        it("should set lastReadAt when fetching a completed session", async () => {
+            const sessionId = await createCompletedSession(sessionManager);
+            const before = new Date();
+            await runFetchAnswersCommand([sessionId]);
+            const after = new Date();
+            const answers = await sessionManager.getSessionAnswers(sessionId);
+            expect(answers).not.toBeNull();
+            expect(answers.lastReadAt).toBeDefined();
+            const readAt = new Date(answers.lastReadAt);
+            expect(readAt.getTime()).toBeGreaterThanOrEqual(before.getTime() - 1000);
+            expect(readAt.getTime()).toBeLessThanOrEqual(after.getTime() + 1000);
+        });
+        it("should not appear in unread list after being fetched", async () => {
+            const sessionId = await createCompletedSession(sessionManager);
+            // Before fetch — should be unread
+            const unreadBefore = await sessionManager.getUnreadSessions();
+            expect(unreadBefore).toContain(sessionId);
+            await runFetchAnswersCommand([sessionId]);
+            // After fetch — should be removed from unread list
+            const unreadAfter = await sessionManager.getUnreadSessions();
+            expect(unreadAfter).not.toContain(sessionId);
+            // Running --unread should also not show it
+            consoleLogSpy.mockClear();
+            await runFetchAnswersCommand(["--unread"]);
+            const unreadOutput = consoleLogSpy.mock.calls.map((c) => c[0]).join("\n");
+            expect(unreadOutput).not.toContain(sessionId.slice(0, 8));
+        });
+    });
+});

package/dist/src/cli/commands/__tests__/history.test.js

@@ -0,0 +1,211 @@
+/**
+ * Integration tests for the `auq history` CLI command.
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { promises as fs } from "fs";
+import { SessionManager } from "../../../session/SessionManager.js";
+import { runHistoryCommand } from "../history.js";
+// ── Test directory ─────────────────────────────────────────────────────────
+const testBaseDir = `/tmp/auq-test-history-${process.pid}`;
+// Stub getSessionDirectory so the history command always targets our temp dir.
+vi.mock("../../../session/utils.js", async (importOriginal) => {
+    const actual = (await importOriginal());
+    return {
+        ...actual,
+        getSessionDirectory: () => testBaseDir,
+    };
+});
+// ── Test fixtures ───────────────────────────────────────────────────────────
+const sampleQuestions = [
+    {
+        title: "Database",
+        prompt: "Which database should we use?",
+        options: [
+            { label: "Postgres", description: "Relational, reliable" },
+            { label: "Redis", description: "In-memory cache" },
+        ],
+        multiSelect: false,
+    },
+    {
+        title: "Auth",
+        prompt: "Which auth method?",
+        options: [
+            { label: "JWT", description: "Stateless tokens" },
+            { label: "Cookies", description: "Server-side sessions" },
+        ],
+        multiSelect: false,
+    },
+];
+async function createCompletedSession(mgr, opts) {
+    const id = await mgr.createSession(sampleQuestions);
+    await mgr.saveSessionAnswers(id, {
+        sessionId: id,
+        timestamp: new Date().toISOString(),
+        answers: sampleQuestions.map((q, i) => ({
+            questionIndex: i,
+            timestamp: new Date().toISOString(),
+            selectedOption: q.options[0].label,
+        })),
+    });
+    await mgr.updateSessionStatus(id, "completed");
+    if (opts?.read) {
+        await mgr.markSessionAsRead(id);
+    }
+    return id;
+}
+async function createRejectedSession(mgr) {
+    const id = await mgr.createSession(sampleQuestions);
+    await mgr.rejectSession(id, "not relevant");
+    return id;
+}
+async function createAbandonedSession(mgr) {
+    const id = await mgr.createSession(sampleQuestions);
+    await mgr.updateSessionStatus(id, "abandoned");
+    return id;
+}
+// ── Test Suite ──────────────────────────────────────────────────────────────
+describe("history command", () => {
+    let sessionManager;
+    let consoleLogSpy;
+    let consoleErrorSpy;
+    beforeEach(async () => {
+        await fs.rm(testBaseDir, { force: true, recursive: true }).catch(() => { });
+        sessionManager = new SessionManager({ baseDir: testBaseDir });
+        await sessionManager.initialize();
+        consoleLogSpy = vi.spyOn(console, "log").mockImplementation(() => { });
+        consoleErrorSpy = vi.spyOn(console, "error").mockImplementation(() => { });
+        process.exitCode = undefined;
+    });
+    afterEach(async () => {
+        consoleLogSpy.mockRestore();
+        consoleErrorSpy.mockRestore();
+        process.exitCode = undefined;
+        await fs.rm(testBaseDir, { force: true, recursive: true }).catch(() => { });
+    });
+    // ── List (default) ──────────────────────────────────────────────────────
+    describe("list (default)", () => {
+        it("should list non-abandoned sessions by default", async () => {
+            await createCompletedSession(sessionManager);
+            const abandonedId = await createAbandonedSession(sessionManager);
+            await runHistoryCommand([]);
+            const output = consoleLogSpy.mock.calls.map((c) => c[0]).join("\n");
+            expect(output).toContain("completed");
+            // Abandoned session's short ID should not appear as a table row
+            expect(output).not.toContain(abandonedId.slice(0, 8));
+        });
+        it("should show abandoned hint when hidden", async () => {
+            await createCompletedSession(sessionManager);
+            await createAbandonedSession(sessionManager);
+            await runHistoryCommand([]);
+            const output = consoleLogSpy.mock.calls.map((c) => c[0]).join("\n");
+            expect(output).toContain("abandoned hidden");
+            expect(output).toContain("--all");
+        });
+        it("should show all with --all flag", async () => {
+            await createCompletedSession(sessionManager);
+            const abandonedId = await createAbandonedSession(sessionManager);
+            await runHistoryCommand(["--all"]);
+            const output = consoleLogSpy.mock.calls.map((c) => c[0]).join("\n");
+            expect(output).toContain(abandonedId.slice(0, 8));
+        });
+        it("should show empty state message", async () => {
+            await runHistoryCommand([]);
+            const output = consoleLogSpy.mock.calls.map((c) => c[0]).join("\n");
+            expect(output).toContain("No sessions found");
+        });
+        it("should limit output with --limit", async () => {
+            await createCompletedSession(sessionManager);
+            await createCompletedSession(sessionManager);
+            await createCompletedSession(sessionManager);
+            await runHistoryCommand(["--limit", "2"]);
+            const output = consoleLogSpy.mock.calls.map((c) => c[0]).join("\n");
+            // Match 8-character lowercase hex strings (UUID short IDs)
+            const matches = output.match(/[a-f0-9]{8}/g) || [];
+            const uniqueIds = [...new Set(matches)];
+            expect(uniqueIds.length).toBeLessThanOrEqual(2);
+        });
+        it("should filter unread with --unread", async () => {
+            const unreadId = await createCompletedSession(sessionManager);
+            await createCompletedSession(sessionManager, { read: true });
+            await runHistoryCommand(["--unread"]);
+            const output = consoleLogSpy.mock.calls.map((c) => c[0]).join("\n");
+            expect(output).toContain(unreadId.slice(0, 8));
+        });
+        it("should search with --search", async () => {
+            await createCompletedSession(sessionManager);
+            await runHistoryCommand(["--search", "database"]);
+            const output = consoleLogSpy.mock.calls.map((c) => c[0]).join("\n");
+            expect(output).toContain("completed");
+        });
+        it("should output JSON with --json", async () => {
+            await createCompletedSession(sessionManager);
+            await runHistoryCommand(["--json"]);
+            const output = consoleLogSpy.mock.calls.map((c) => c[0]).join("\n");
+            const parsed = JSON.parse(output);
+            expect(Array.isArray(parsed)).toBe(true);
+            expect(parsed[0]).toHaveProperty("sessionId");
+            expect(parsed[0]).toHaveProperty("status");
+            expect(parsed[0]).toHaveProperty("questionCount");
+        });
+        it("should find session with --session", async () => {
+            const id = await createCompletedSession(sessionManager);
+            await runHistoryCommand(["--session", id.slice(0, 8)]);
+            const output = consoleLogSpy.mock.calls.map((c) => c[0]).join("\n");
+            expect(output).toContain(id.slice(0, 8));
+        });
+        it("should error for --session with no match", async () => {
+            await runHistoryCommand(["--session", "00000000"]);
+            expect(process.exitCode).toBe(1);
+        });
+    });
+    // ── Show ────────────────────────────────────────────────────────────────
+    describe("show", () => {
+        it("should show session details", async () => {
+            const id = await createCompletedSession(sessionManager);
+            await runHistoryCommand(["show", id]);
+            const output = consoleLogSpy.mock.calls.map((c) => c[0]).join("\n");
+            expect(output).toContain(id);
+            expect(output).toContain("completed");
+            expect(output).toContain("Which database should we use?");
+        });
+        it("should show all options with (selected) prefix for answered options", async () => {
+            const id = await createCompletedSession(sessionManager);
+            await runHistoryCommand(["show", id]);
+            const output = consoleLogSpy.mock.calls.map((c) => c[0]).join("\n");
+            expect(output).toContain("(selected)");
+            expect(output).toContain("Postgres");
+            expect(output).toContain("Redis");
+        });
+        it("should resolve short session ID", async () => {
+            const id = await createCompletedSession(sessionManager);
+            await runHistoryCommand(["show", id.slice(0, 8)]);
+            const output = consoleLogSpy.mock.calls.map((c) => c[0]).join("\n");
+            expect(output).toContain(id);
+        });
+        it("should error for non-existent session", async () => {
+            await runHistoryCommand(["show", "nonexistent-id"]);
+            expect(process.exitCode).toBe(1);
+        });
+        it("should show rejected session", async () => {
+            const id = await createRejectedSession(sessionManager);
+            await runHistoryCommand(["show", id]);
+            const output = consoleLogSpy.mock.calls.map((c) => c[0]).join("\n");
+            expect(output).toContain("rejected");
+        });
+        it("should show abandoned session", async () => {
+            const id = await createAbandonedSession(sessionManager);
+            await runHistoryCommand(["show", id]);
+            const output = consoleLogSpy.mock.calls.map((c) => c[0]).join("\n");
+            expect(output).toContain("abandoned");
+        });
+        it("should output JSON with --json", async () => {
+            const id = await createCompletedSession(sessionManager);
+            await runHistoryCommand(["show", id, "--json"]);
+            const output = consoleLogSpy.mock.calls.map((c) => c[0]).join("\n");
+            const parsed = JSON.parse(output);
+            expect(parsed.sessionId).toBe(id);
+            expect(parsed.questions).toBeInstanceOf(Array);
+            expect(parsed.questions[0].options).toBeInstanceOf(Array);
+        });
+    });
+});

package/dist/src/cli/commands/answer.js

@@ -84,6 +84,17 @@ export async function runAnswerCommand(args) {
         }
     }
     catch (err) {
+        if (!jsonMode) {
+            process.stderr.write(`Error: Invalid --answers JSON format.\n\n` +
+                `Expected format:\n` +
+                `  auq answer <sessionId> --answers '{"0": {"selectedOption": "Label Name"}}'\n\n` +
+                `Answer object keys are question indices (0, 1, 2, ...). Each value can have:\n` +
+                `  \u2022 selectedOption: "Label"      \u2014 for single-select questions\n` +
+                `  \u2022 selectedOptions: ["A", "B"]  \u2014 for multi-select questions\n` +
+                `  \u2022 customText: "free text"       \u2014 for custom/other input\n\n` +
+                `Example (multi-question):\n` +
+                `  auq answer abc123 --answers '{"0": {"selectedOption": "Yes"}, "1": {"customText": "my input"}}'\n\n`);
+        }
         outputResult({
             success: false,
             error: `Invalid answers JSON: ${err instanceof Error ? err.message : String(err)}`,

package/dist/src/cli/commands/config.js

@@ -155,6 +155,36 @@ async function configGet(args) {
             return;
         }
         const value = getNestedValue(config, key);
+        // Special handling for renderer key: show env var override and source
+        if (key === "renderer") {
+            const envRenderer = process.env.AUQ_RENDERER;
+            let displayValue;
+            let source;
+            if (envRenderer) {
+                displayValue = envRenderer;
+                source = "AUQ_RENDERER";
+            }
+            else {
+                const paths = getConfigPaths();
+                const localConfig = readConfigFileForWrite(paths.local);
+                const globalConfig = readConfigFileForWrite(paths.global);
+                const explicitlySet = localConfig.renderer !== undefined || globalConfig.renderer !== undefined;
+                displayValue = String(value);
+                source = explicitlySet ? "config" : "default";
+            }
+            if (jsonMode) {
+                console.log(JSON.stringify({ success: true, key, value: displayValue, source }, null, 2));
+            }
+            else {
+                const suffix = source === "AUQ_RENDERER"
+                    ? " (from AUQ_RENDERER)"
+                    : source === "default"
+                        ? " (default)"
+                        : "";
+                console.log(`${key} = ${displayValue}${suffix}`);
+            }
+            return;
+        }
         if (jsonMode) {
             console.log(JSON.stringify({ success: true, key, value }, null, 2));
         }
@@ -210,6 +240,22 @@ async function configSet(args) {
         const issues = validation.error.issues
             .map((i) => `${i.path.join(".")}: ${i.message}`)
             .join("; ");
+        // Build key-specific hint for human-readable mode
+        if (!jsonMode) {
+            const hints = {
+                maxOptions: "Expected: number between 2 and 10",
+                maxQuestions: "Expected: number between 1 and 10",
+                sessionTimeout: "Expected: number (milliseconds, e.g. 300000 for 5 minutes)",
+                renderer: 'Expected: \"ink\" or \"opentui\"',
+                staleAction: 'Expected: \"warn\", \"remove\", or \"archive\"',
+                theme: "Expected: a valid theme name (see auq config get theme)",
+                language: "Expected: a language code (e.g. \"en\", \"ko\")",
+            };
+            const hint = hints[key];
+            process.stderr.write(`Error: Invalid value "${rawValue}" for key "${key}".\n\n` +
+                (hint ? `${hint}\n\n` : "") +
+                `Usage: auq config set ${key} <value> [--global]\n\n`);
+        }
         outputResult({
             success: false,
             error: `Invalid value for "${key}": ${issues}`,
@@ -255,6 +301,8 @@ export async function runConfigCommand(args) {
             console.log("  auq config get staleThreshold --json");
             console.log("  auq config set staleThreshold 3600000");
             console.log("  auq config set notifyOnStale false --global");
+            console.log("  auq config get renderer");
+            console.log("  auq config set renderer opentui");
             if (subcommand !== undefined) {
                 process.exitCode = 1;
             }