feat(desktop): clarify inspector readability path

Co-Authored-By: Paperclip <noreply@paperclip.ing>

README.md

@@ -83,5 +83,6 @@ pnpm run desktop:tauri:dev
 - 当前前端还通过共享错误映射层统一消费 `redis-core` 的稳定错误码，使连接测试、浏览、读取、保存、TTL 和命令执行失败都落到一致的操作提示上。
 - `inspect_redis_key` 与 `update_redis_key_ttl` 已在桌面桥可用；当前 UI 已暴露 TTL 设置与移除控制，但删除执行仍保持未开放状态。
 - inspector 现在对 `hash/list/set/zset/stream` 提供结构化只读面板，不再要求操作者从原始 JSON 文本中手动解析 typed value。
+- inspector 现在还会明确显示当前 inspect 状态、value surface 语义、下一步操作路径和 key facts，降低 string、structured、missing 和 demo fallback 场景下的误读成本。
 - 连接测试、key browse、value inspector 和命令托盘在 Tauri 桌面运行时走真实后端桥；浏览器态 `pnpm run desktop:dev` 会明确回退到 demo 数据，不伪装成真实 Redis 行为。
 - 具体 UI/UX 边界与 QA 验收入口见 `docs/frontend-workspace-baseline.md` 和 `docs/qa/acceptance-matrix.md`。

apps/desktop/src/App.tsx

@@ -37,6 +37,13 @@ import {
 } from "./components/ui/dialog";
 import { Input } from "./components/ui/input";
 import { Textarea } from "./components/ui/textarea";
+import {
+  isLocalSmokeFixtureConnection,
+  localSmokeFixtureCommandPresets,
+  localSmokeFixtureExpectedKeys,
+  localSmokeFixtureProfileId,
+  localSmokeFixtureSearchText,
+} from "./lib/local-smoke-fixture";
 import {
   toBackendError,
   type BackendErrorContext,
@@ -45,10 +52,34 @@ import {
   toBackendErrorNotice,
   type OperatorNotice,
 } from "./lib/operator-notices";
+import { buildQaSnapshot } from "./lib/qa-snapshot";
 import {
   buildStructuredInspectorSections,
   type StructuredInspectorSection,
 } from "./lib/structured-inspector";
+import {
+  buildInspectorReadabilitySummary,
+  type InspectorFact,
+} from "./lib/inspector-readability";
+import {
+  appendWorkspaceKeyRecords,
+  filterWorkspaceKeys,
+  replaceWorkspaceKeyRecord,
+  resolveSelectedWorkspaceKey,
+  resolveSelectedWorkspaceKeyId,
+} from "./lib/key-workspace-state";
+import {
+  buildInspectorEmptyStateMessage,
+  buildKeyBrowserEmptyStateMessage,
+  buildKeyBrowserStatusMessage,
+  resolveKeyBrowserSearchState,
+} from "./lib/key-browser-search";
+import {
+  parseDemoTtlToSeconds,
+  persistDemoKeyTtl,
+  updateDemoKeyTtl,
+  updateDemoStringValue,
+} from "./lib/demo-workspace";
 import { cn } from "./lib/utils";
 
 declare const __APP_VERSION__: string;
@@ -293,7 +324,7 @@ const initialConnections: ConnectionProfile[] = [
   },
 ];
 
-const keyData: KeyRecord[] = [
+const initialDemoKeys: KeyRecord[] = [
   {
     id: "session:42",
     name: "session:42",
@@ -373,11 +404,12 @@ const initialConsoleHistory: ConsoleEntry[] = [
 
 function App() {
   const [connections, setConnections] = useState(initialConnections);
+  const [demoKeys, setDemoKeys] = useState(initialDemoKeys);
   const [activeConnectionId, setActiveConnectionId] = useState(initialConnections[0].id);
   const [activeDb, setActiveDb] = useState(databases[0]);
   const [search, setSearch] = useState("");
-  const [selectedKeyId, setSelectedKeyId] = useState<string | null>(keyData[1].id);
-  const [draftValue, setDraftValue] = useState(keyData[1].value);
+  const [selectedKeyId, setSelectedKeyId] = useState<string | null>(initialDemoKeys[1].id);
+  const [draftValue, setDraftValue] = useState(initialDemoKeys[1].value);
   const [consoleInput, setConsoleInput] = useState("GET cache:homepage");
   const [consoleHistory, setConsoleHistory] = useState(initialConsoleHistory);
   const [bootstrap, setBootstrap] = useState(fallbackBootstrap);
@@ -422,18 +454,14 @@ function App() {
     connections.find((connection) => connection.id === activeConnectionId) ??
     connections[0];
 
-  const demoQuery = deferredSearch.trim().toLowerCase();
-  const demoKeys = !demoQuery
-    ? keyData
-    : keyData.filter((item) => item.name.toLowerCase().includes(demoQuery));
-  const filteredKeys = tauriAvailable ? liveKeys : demoKeys;
+  const searchState = resolveKeyBrowserSearchState(search);
+  const deferredSearchState = resolveKeyBrowserSearchState(deferredSearch);
+  const filteredDemoKeys = filterWorkspaceKeys(demoKeys, deferredSearchState.trimmedQuery);
+  const filteredKeys = tauriAvailable ? liveKeys : filteredDemoKeys;
   const draftErrors = validateConnectionDraft(connectionDraft, connections);
   const draftErrorList = Object.values(draftErrors);
 
-  const selectedKey =
-    filteredKeys.length === 0
-      ? null
-      : filteredKeys.find((item) => item.id === selectedKeyId) ?? filteredKeys[0];
+  const selectedKey = resolveSelectedWorkspaceKey(filteredKeys, selectedKeyId);
 
   const isEditable = tauriAvailable
     ? selectedValueRecord?.write_capability === "replace_string" &&
@@ -451,14 +479,27 @@ function App() {
     !isInspectorLoading &&
     structuredInspectorSections.length > 0 &&
     !isEditable;
-
-  const supportNote = tauriAvailable
-    ? buildLiveSupportNote(selectedValueRecord, selectedKey)
-    : (selectedKey?.summary ??
-      `Search currently returns zero keys in ${activeDb}. This is an intentional empty state, not a backend failure.`);
   const ttlWriteSupported = tauriAvailable
     ? selectedValueRecord?.ttl_write_supported === true
     : selectedKey !== null;
+  const inspectorReadability = buildInspectorReadabilitySummary({
+    databaseLabel: activeDb,
+    runtimeMode: tauriAvailable ? "live" : "demo",
+    selectedKey:
+      selectedKey === null
+        ? null
+        : {
+            name: selectedKey.name,
+            type: selectedKey.type,
+            ttl: selectedKey.ttl,
+          },
+    record: selectedValueRecord,
+    isLoading: isInspectorLoading,
+    isEditable,
+    ttlWriteSupported,
+  });
+  const localSmokeFixtureActive = isLocalSmokeFixtureConnection(activeConnection);
+  const localSmokeFilterActive = search.trim() === localSmokeFixtureSearchText;
   const ttlDraftError = ttlDraft.trim() ? validateTtlDraft(ttlDraft) : null;
   const canSubmitTtlUpdate =
     selectedKey !== null &&
@@ -474,23 +515,41 @@ function App() {
       ? selectedValueRecord?.metadata.ttl.kind !== "persistent"
       : selectedKey?.ttl !== "persistent");
   const latestConsoleEntry = consoleHistory[0] ?? null;
-  const qaSnapshot = [
-    `app=${bootstrap.app_name}`,
-    `version=${appVersion}`,
-    `runtime=${runtimeMode}`,
-    `build=${buildMode}`,
-    `connection=${activeConnection.name}`,
-    `endpoint=${formatEndpoint(activeConnection.target)}`,
-    `database=${activeDb}`,
-    `selectedKey=${selectedKey?.name ?? "none"}`,
-    `selectedType=${selectedKey?.type ?? "none"}`,
-    `selectedTtl=${selectedKey?.ttl ?? "none"}`,
-    `browseVisible=${filteredKeys.length}${tauriAvailable && liveHasMore ? "+" : ""}`,
-    `latestCommand=${latestConsoleEntry?.command ?? "none"}`,
-    `latestCommandSource=${latestConsoleEntry?.source ?? "none"}`,
-    `latestCommandStatus=${latestConsoleEntry?.status ?? "none"}`,
-    `banner=${banner.message}`,
-  ].join("\n");
+  const keyBrowserStatusMessage = buildKeyBrowserStatusMessage({
+    databaseLabel: activeDb,
+    visibleCount: filteredKeys.length,
+    hasMore: tauriAvailable && liveHasMore,
+    isLoading: isBrowseLoading,
+    search: deferredSearchState,
+  });
+  const keyBrowserEmptyStateMessage = buildKeyBrowserEmptyStateMessage({
+    databaseLabel: activeDb,
+    isLoading: isBrowseLoading,
+    search: deferredSearchState,
+  });
+  const inspectorEmptyStateMessage = buildInspectorEmptyStateMessage(
+    activeDb,
+    deferredSearchState,
+  );
+  const qaSnapshot = buildQaSnapshot({
+    appName: bootstrap.app_name,
+    appVersion,
+    runtimeMode,
+    buildMode,
+    connectionName: activeConnection.name,
+    endpoint: formatEndpoint(activeConnection.target),
+    databaseLabel: activeDb,
+    smokeFixtureActive: localSmokeFixtureActive,
+    smokeFilter: localSmokeFilterActive ? localSmokeFixtureSearchText : search,
+    selectedKeyName: selectedKey?.name ?? null,
+    selectedKeyType: selectedKey?.type ?? null,
+    selectedKeyTtl: selectedKey?.ttl ?? null,
+    browseVisibleCount: `${filteredKeys.length}${tauriAvailable && liveHasMore ? "+" : ""}`,
+    latestCommand: latestConsoleEntry?.command ?? null,
+    latestCommandSource: latestConsoleEntry?.source ?? null,
+    latestCommandStatus: latestConsoleEntry?.status ?? null,
+    bannerMessage: banner.message,
+  });
 
   useEffect(() => {
     if (!tauriAvailable) {
@@ -544,7 +603,7 @@ function App() {
     const request: RedisKeyBrowseRequest = {
       connection: toRedisConnectionRequest(activeConnection, activeDb),
       cursor: "0",
-      pattern: toRedisSearchPattern(deferredSearch),
+      pattern: deferredSearchState.requestPattern,
       page_size: browsePageSize,
     };
 
@@ -569,9 +628,7 @@ function App() {
           setLiveKeys(nextKeys);
           setLiveNextCursor(result.next_cursor);
           setLiveHasMore(result.has_more);
-          setSelectedKeyId((current) =>
-            nextKeys.some((item) => item.id === current) ? current : (nextKeys[0]?.id ?? null),
-          );
+          setSelectedKeyId((current) => resolveSelectedWorkspaceKeyId(nextKeys, current));
           setIsBrowseLoading(false);
         });
       })
@@ -600,7 +657,7 @@ function App() {
     return () => {
       active = false;
     };
-  }, [activeConnectionId, activeDb, deferredSearch, tauriAvailable]);
+  }, [activeConnectionId, activeDb, deferredSearchState.requestPattern, tauriAvailable]);
 
   useEffect(() => {
     if (!tauriAvailable) {
@@ -644,7 +701,7 @@ function App() {
         const nextRecord = toLiveKeyRecordFromValue(record);
         startTransition(() => {
           setSelectedValueRecord(record);
-          setLiveKeys((current) => replaceKeyRecord(current, nextRecord));
+          setLiveKeys((current) => replaceWorkspaceKeyRecord(current, nextRecord));
           setDraftValue(
             record.data.kind === "string" && record.write_capability === "replace_string"
               ? formatRedisValueContent(record.data.value)
@@ -723,6 +780,60 @@ function App() {
     });
   };
 
+  const handleUseLocalSmokeFixture = () => {
+    const existingFixture = connections.find(isLocalSmokeFixtureConnection);
+    const fixtureConnection =
+      existingFixture ??
+      {
+        id: localSmokeFixtureProfileId,
+        name: localSmokeFixtureProfileId,
+        environment: "local" as const,
+        detail: "Fixture profile",
+        status: "idle" as const,
+        password: "",
+        target: {
+          host: "127.0.0.1",
+          port: 6380,
+          database: 0,
+          username: null,
+          tls_mode: "disabled" as const,
+        },
+      };
+
+    startTransition(() => {
+      if (!existingFixture) {
+        setConnections((current) => [fixtureConnection, ...current]);
+      }
+      setActiveConnectionId(fixtureConnection.id);
+      setActiveDb(formatDatabaseLabel(fixtureConnection.target.database));
+      setSelectedKeyId(null);
+      setSearch(localSmokeFixtureSearchText);
+      setConsoleInput(localSmokeFixtureCommandPresets[0].command);
+      showAccentBanner(
+        "Loaded the local smoke fixture profile, narrowed the browser to smoke:* keys, and primed the command tray with PING.",
+      );
+    });
+  };
+
+  const handleFocusLocalSmokeKeys = () => {
+    startTransition(() => {
+      setSearch(localSmokeFixtureSearchText);
+      setSelectedKeyId(null);
+      showNeutralBanner(
+        `Focused the browser on ${localSmokeFixtureSearchText} for local smoke verification in ${activeDb}.`,
+      );
+    });
+  };
+
+  const handleApplyLocalSmokeCommandPreset = (command: string) => {
+    startTransition(() => {
+      setConsoleInput(command);
+      showNeutralBanner(
+        `Loaded ${command} into the command tray so QA can execute the next safe smoke step without retyping.`,
+      );
+    });
+  };
+
   const handleCreateDraftConnection = () => {
     if (draftErrorList.length > 0) {
       showNeutralBanner(`Connection draft is incomplete: ${draftErrorList[0]}`);
@@ -766,9 +877,12 @@ function App() {
     }
 
     if (!tauriAvailable) {
-      showNeutralBanner(
-        `Saved mock string value for ${selectedKey.name} in ${activeDb}. Backend persistence is not wired yet.`,
-      );
+      startTransition(() => {
+        setDemoKeys((current) => updateDemoStringValue(current, selectedKey.name, draftValue));
+        showNeutralBanner(
+          `Saved session-local mock string value for ${selectedKey.name} in ${activeDb}. Backend persistence is still unavailable in browser demo mode.`,
+        );
+      });
       return;
     }
 
@@ -791,7 +905,7 @@ function App() {
       const nextRecord = toLiveKeyRecordFromValue(result);
       startTransition(() => {
         setSelectedValueRecord(result);
-        setLiveKeys((current) => replaceKeyRecord(current, nextRecord));
+        setLiveKeys((current) => replaceWorkspaceKeyRecord(current, nextRecord));
         setDraftValue(
           result.data.kind === "string"
             ? formatRedisValueContent(result.data.value)
@@ -839,9 +953,14 @@ function App() {
     }
 
     if (!tauriAvailable) {
-      showNeutralBanner(
-        `Browser dev mode keeps TTL changes in demo fallback for ${selectedKey.name}. Use desktop runtime for a live TTL update.`,
-      );
+      startTransition(() => {
+        setDemoKeys((current) =>
+          updateDemoKeyTtl(current, selectedKey.name, Number.parseInt(ttlDraft, 10)),
+        );
+        showNeutralBanner(
+          `Updated session-local mock TTL for ${selectedKey.name} in ${activeDb}. Use desktop runtime for a live TTL change.`,
+        );
+      });
       return;
     }
 
@@ -893,9 +1012,13 @@ function App() {
     }
 
     if (!tauriAvailable) {
-      showNeutralBanner(
-        `Browser dev mode keeps TTL removal in demo fallback for ${selectedKey.name}. Use desktop runtime for a live TTL change.`,
-      );
+      startTransition(() => {
+        setDemoKeys((current) => persistDemoKeyTtl(current, selectedKey.name));
+        setTtlDraft("");
+        showNeutralBanner(
+          `Removed session-local mock TTL for ${selectedKey.name} in ${activeDb}. Use desktop runtime for a live TTL change.`,
+        );
+      });
       return;
     }
 
@@ -967,7 +1090,7 @@ function App() {
       const nextRecord = toLiveKeyRecordFromValue(result);
       startTransition(() => {
         setSelectedValueRecord(result);
-        setLiveKeys((current) => replaceKeyRecord(current, nextRecord));
+        setLiveKeys((current) => replaceWorkspaceKeyRecord(current, nextRecord));
         setDraftValue(
           result.data.kind === "string" && result.write_capability === "replace_string"
             ? formatRedisValueContent(result.data.value)
@@ -1020,11 +1143,15 @@ function App() {
         metadata,
       };
       setSelectedValueRecord(nextRecord);
-      setLiveKeys((current) => replaceKeyRecord(current, toLiveKeyRecordFromValue(nextRecord)));
+      setLiveKeys((current) =>
+        replaceWorkspaceKeyRecord(current, toLiveKeyRecordFromValue(nextRecord)),
+      );
       return;
     }
 
-    setLiveKeys((current) => replaceKeyRecord(current, toLiveKeyRecordFromMetadata(metadata)));
+    setLiveKeys((current) =>
+      replaceWorkspaceKeyRecord(current, toLiveKeyRecordFromMetadata(metadata)),
+    );
   };
 
   const handleLoadMoreKeys = async () => {
@@ -1041,14 +1168,14 @@ function App() {
         request: {
           connection: toRedisConnectionRequest(activeConnection, activeDb),
           cursor: liveNextCursor,
-          pattern: toRedisSearchPattern(deferredSearch),
+          pattern: deferredSearchState.requestPattern,
           page_size: browsePageSize,
         } satisfies RedisKeyBrowseRequest,
       });
 
       const nextKeys = result.keys.map(toLiveKeyRecordFromMetadata);
       startTransition(() => {
-        setLiveKeys((current) => appendKeyRecords(current, nextKeys));
+        setLiveKeys((current) => appendWorkspaceKeyRecords(current, nextKeys));
         setLiveNextCursor(result.next_cursor);
         setLiveHasMore(result.has_more);
         setIsBrowseLoading(false);
@@ -1532,6 +1659,67 @@ function App() {
                 </div>
               </section>
 
+              <section>
+                <SectionEyebrow icon={<Activity className="h-4 w-4" />} label="Local smoke assist" />
+                <div className="mt-3 rounded-[22px] border border-[var(--line-soft)] bg-[var(--surface-base)] p-4">
+                  <div className="flex items-start justify-between gap-3">
+                    <div>
+                      <p className="text-sm font-medium text-[var(--ink-0)]">
+                        Seeded fixture path for desktop smoke runs
+                      </p>
+                      <p className="mt-1 text-sm text-[var(--ink-soft)]">
+                        Mirrors `docs/qa/local-desktop-smoke.md` and keeps the safe validation path visible inside the shell.
+                      </p>
+                    </div>
+                    <Badge variant={localSmokeFixtureActive ? "accent" : "neutral"}>
+                      {localSmokeFixtureActive ? "active" : "inactive"}
+                    </Badge>
+                  </div>
+
+                  <div className="mt-3 flex flex-wrap gap-2">
+                    <Badge variant="neutral">127.0.0.1:6380</Badge>
+                    <Badge variant="neutral">db0</Badge>
+                    <Badge variant="neutral">{localSmokeFixtureExpectedKeys.length} seeded keys</Badge>
+                  </div>
+
+                  <div className="mt-3 grid grid-cols-2 gap-2">
+                    <Button variant="outline" size="sm" onClick={handleUseLocalSmokeFixture}>
+                      Use fixture
+                    </Button>
+                    <Button variant="outline" size="sm" onClick={handleFocusLocalSmokeKeys}>
+                      Focus smoke:*
+                    </Button>
+                  </div>
+
+                  <div className="mt-3 space-y-2">
+                    {localSmokeFixtureCommandPresets.map((preset) => (
+                      <button
+                        key={preset.id}
+                        type="button"
+                        onClick={() => handleApplyLocalSmokeCommandPreset(preset.command)}
+                        className="w-full rounded-[18px] border border-[var(--line-soft)] bg-[var(--surface-muted)] px-3 py-2 text-left transition hover:border-[var(--line-strong)]"
+                      >
+                        <p className="font-mono text-sm text-[var(--ink-0)]">{preset.label}</p>
+                        <p className="mt-1 text-xs text-[var(--ink-soft)]">{preset.summary}</p>
+                      </button>
+                    ))}
+                  </div>
+
+                  <div className="mt-3 rounded-[18px] border border-[var(--line-soft)] bg-[var(--surface-muted)] px-3 py-3">
+                    <p className="font-mono text-[11px] uppercase tracking-[0.18em] text-[var(--ink-muted)]">
+                      Seeded keys
+                    </p>
+                    <div className="mt-2 flex flex-wrap gap-2">
+                      {localSmokeFixtureExpectedKeys.map((keyName) => (
+                        <Badge key={keyName} variant="neutral" className="normal-case tracking-normal">
+                          {keyName}
+                        </Badge>
+                      ))}
+                    </div>
+                  </div>
+                </div>
+              </section>
+
               <section>
                 <SectionEyebrow icon={<ClipboardList className="h-4 w-4" />} label="QA snapshot" />
                 <div className="mt-3 rounded-[22px] border border-[var(--line-soft)] bg-[var(--surface-base)] p-4">
@@ -1571,7 +1759,7 @@ function App() {
                 <Badge variant="neutral">
                   {tauriAvailable
                     ? `${filteredKeys.length}${liveHasMore ? "+" : ""} visible in ${activeDb}`
-                    : `${filteredKeys.length} of ${keyData.length} keys in ${activeDb}`}
+                    : `${filteredKeys.length} of ${demoKeys.length} keys in ${activeDb}`}
                 </Badge>
               </div>
 
@@ -1583,7 +1771,25 @@ function App() {
                   className="w-full bg-transparent text-sm text-[var(--ink-0)] outline-none placeholder:text-[var(--ink-muted)]"
                   placeholder="Search key name or pattern"
                 />
+                {searchState.mode === "all" ? null : (
+                  <Button
+                    variant="ghost"
+                    size="sm"
+                    onClick={() => setSearch("")}
+                    className="shrink-0 px-2 py-1 text-xs"
+                  >
+                    Clear
+                  </Button>
+                )}
               </label>
+              <div className="flex items-center justify-between gap-3 text-xs text-[var(--ink-muted)]">
+                <div className="flex items-center gap-2">
+                  <Badge variant="neutral" className="normal-case tracking-normal">
+                    {deferredSearchState.mode === "all" ? "all keys" : deferredSearchState.mode === "pattern" ? "pattern" : "contains"}
+                  </Badge>
+                  <p>{keyBrowserStatusMessage}</p>
+                </div>
+              </div>
             </div>
 
             <div className="mt-4 min-h-0 flex-1 space-y-2 overflow-auto pr-1">
@@ -1621,9 +1827,7 @@ function App() {
 
               {filteredKeys.length === 0 ? (
                 <div className="rounded-[24px] border border-dashed border-[var(--line-strong)] bg-[var(--surface-base)] px-4 py-8 text-center text-sm text-[var(--ink-soft)]">
-                  {isBrowseLoading
-                    ? `Loading keys from ${activeDb}...`
-                    : `No keys match the current pattern in ${activeDb}.`}
+                  {keyBrowserEmptyStateMessage}
                 </div>
               ) : null}
 
@@ -1654,6 +1858,7 @@ function App() {
                   <div className="flex items-center gap-2">
                     <Badge variant="neutral">{selectedKey.type}</Badge>
                     <Badge variant="neutral">TTL {selectedKey.ttl}</Badge>
+                    <Badge variant="accent">{inspectorReadability.status}</Badge>
                   </div>
                 ) : null}
               </div>
@@ -1663,16 +1868,19 @@ function App() {
                   <div className="flex items-center justify-between gap-3">
                     <p className="text-sm font-medium text-[var(--ink-0)]">Value surface</p>
                     <span className="font-mono text-xs text-[var(--ink-muted)]">
-                      {selectedKey
-                        ? isInspectorLoading
-                          ? "loading"
-                          : isEditable
-                            ? "editable"
-                            : "read only"
-                        : "awaiting selection"}
+                      {inspectorReadability.status}
                     </span>
                   </div>
 
+                  <div className="mt-3 rounded-[20px] border border-[var(--line-soft)] bg-[var(--surface-muted)] px-4 py-3">
+                    <p className="text-sm font-medium text-[var(--ink-0)]">
+                      {inspectorReadability.surfaceTitle}
+                    </p>
+                    <p className="mt-1 text-sm text-[var(--ink-soft)]">
+                      {inspectorReadability.surfaceDescription}
+                    </p>
+                  </div>
+
                   {selectedKey ? (
                     showStructuredInspector ? (
                       <StructuredInspectorPanels sections={structuredInspectorSections} />
@@ -1690,7 +1898,7 @@ function App() {
                     )
                   ) : (
                     <div className="mt-3 flex h-64 items-center justify-center rounded-[22px] border border-dashed border-[var(--line-strong)] bg-[var(--surface-muted)] px-6 text-center text-sm text-[var(--ink-soft)]">
-                      No key matches the current pattern in {activeDb}. Clear or adjust the search to restore an inspector target.
+                      {inspectorEmptyStateMessage}
                     </div>
                   )}
 
@@ -1750,17 +1958,29 @@ function App() {
                       </DialogContent>
                     </Dialog>
                   </div>
+
+                  <div className="mt-3 rounded-[20px] border border-dashed border-[var(--line-soft)] bg-[var(--surface-muted)] px-4 py-3">
+                    <p className="font-mono text-[11px] uppercase tracking-[0.18em] text-[var(--ink-muted)]">
+                      {inspectorReadability.actionTitle}
+                    </p>
+                    <p className="mt-2 text-sm text-[var(--ink-soft)]">
+                      {inspectorReadability.actionDescription}
+                    </p>
+                  </div>
                 </div>
 
                 <div className="space-y-4">
-                  <InfoCard
-                    title="Key metadata"
+                  <InspectorSummaryCard
+                    title="Inspect summary"
+                    icon={<CircleAlert className="h-4 w-4" />}
+                    surfaceDescription={inspectorReadability.surfaceDescription}
+                    actionTitle={inspectorReadability.actionTitle}
+                    actionDescription={inspectorReadability.actionDescription}
+                  />
+                  <InspectorFactsCard
+                    title="Key facts"
                     icon={<TimerReset className="h-4 w-4" />}
-                    lines={[
-                      `Active DB: ${activeDb}`,
-                      `TTL: ${selectedKey?.ttl ?? "no active key"}`,
-                      `Editor support: ${selectedKey ? (isEditable ? "string write enabled" : "inspection only") : "awaiting matching selection"}`,
-                    ]}
+                    facts={inspectorReadability.facts}
                   />
                   <div className="rounded-[24px] border border-[var(--line-soft)] bg-[var(--surface-base)] p-4">
                     <div className="flex items-center gap-2">
@@ -1825,11 +2045,6 @@ function App() {
                       </div>
                     </div>
                   </div>
-                  <InfoCard
-                    title="Support note"
-                    icon={<CircleAlert className="h-4 w-4" />}
-                    lines={[supportNote]}
-                  />
                 </div>
               </div>
             </div>
@@ -1961,6 +2176,59 @@ function InfoCard({
   );
 }
 
+function InspectorSummaryCard({
+  title,
+  icon,
+  surfaceDescription,
+  actionTitle,
+  actionDescription,
+}: {
+  title: string;
+  icon: ReactElement;
+  surfaceDescription: string;
+  actionTitle: string;
+  actionDescription: string;
+}) {
+  return (
+    <div className="rounded-[24px] border border-[var(--line-soft)] bg-[var(--surface-base)] p-4">
+      <div className="flex items-center gap-2">
+        <span className="text-[var(--accent-strong)]">{icon}</span>
+        <p className="text-sm font-medium text-[var(--ink-0)]">{title}</p>
+      </div>
+
+      <div className="mt-3 space-y-4">
+        <InfoLine label="Current path" value={surfaceDescription} />
+        <InfoLine label={actionTitle} value={actionDescription} />
+      </div>
+    </div>
+  );
+}
+
+function InspectorFactsCard({
+  title,
+  icon,
+  facts,
+}: {
+  title: string;
+  icon: ReactElement;
+  facts: InspectorFact[];
+}) {
+  return (
+    <div className="rounded-[24px] border border-[var(--line-soft)] bg-[var(--surface-base)] p-4">
+      <div className="flex items-center gap-2">
+        <span className="text-[var(--accent-strong)]">{icon}</span>
+        <p className="text-sm font-medium text-[var(--ink-0)]">{title}</p>
+      </div>
+
+      <div className="mt-3 grid gap-3 sm:grid-cols-2">
+        {facts.map((fact) => (
+          <InfoLine key={fact.label} label={fact.label} value={fact.value} />
+        ))}
+      </div>
+    </div>
+  );
+}
+
 function StructuredInspectorPanels({
   sections,
 }: {
@@ -2147,7 +2415,7 @@ function buildMockCommandOutput(command: string, selectedKey: KeyRecord | null)
   }
 
   if (upper === "TTL") {
-    return `(integer) ${selectedKey.ttl === "persistent" ? -1 : selectedKey.ttl.replace(/[^0-9]/g, "")}`;
+    return `(integer) ${parseDemoTtlToSeconds(selectedKey.ttl)}`;
   }
 
   if (upper === "TYPE") {
@@ -2290,39 +2558,6 @@ function toLiveKeyRecordFromValue(record: RedisValueRecord): KeyRecord {
   };
 }
 
-function replaceKeyRecord(current: KeyRecord[], next: KeyRecord) {
-  let replaced = false;
-  const updated = current.map((item) => {
-    if (item.id !== next.id) {
-      return item;
-    }
-
-    replaced = true;
-    return {
-      ...item,
-      ...next,
-    };
-  });
-
-  return replaced ? updated : [next, ...current];
-}
-
-function appendKeyRecords(current: KeyRecord[], next: KeyRecord[]) {
-  const seen = new Set(current.map((item) => item.id));
-  const appended = [...current];
-
-  for (const item of next) {
-    if (seen.has(item.id)) {
-      continue;
-    }
-
-    seen.add(item.id);
-    appended.push(item);
-  }
-
-  return appended;
-}
-
 function buildMetadataPreview(metadata: RedisKeyMetadata) {
   return `${formatRedisKeyTypeLabel(metadata.key_type)} key · TTL ${formatRedisKeyTtl(metadata.ttl)}`;
 }

apps/desktop/src/lib/demo-workspace.test.ts

@@ -0,0 +1,55 @@
+import { describe, expect, it } from "vitest";
+import {
+  buildDemoStringPreview,
+  formatDemoDurationFromMillis,
+  parseDemoTtlToSeconds,
+  persistDemoKeyTtl,
+  updateDemoKeyTtl,
+  updateDemoStringValue,
+  type DemoWorkspaceKey,
+} from "./demo-workspace";
+
+const demoKeys: DemoWorkspaceKey[] = [
+  {
+    id: "cache:homepage",
+    name: "cache:homepage",
+    type: "string",
+    ttl: "48s",
+    preview: "serialized landing payload",
+    editable: true,
+    value: "{\"hero\":\"Redis GUI\"}",
+    summary: "String keys are editable in V1.",
+  },
+];
+
+describe("demo workspace helpers", () => {
+  it("updates string values and refreshes the visible preview", () => {
+    expect(
+      updateDemoStringValue(demoKeys, "cache:homepage", "next value"),
+    ).toEqual([
+      {
+        ...demoKeys[0],
+        value: "next value",
+        preview: "next value",
+      },
+    ]);
+  });
+
+  it("updates TTL state for session-local demo flows", () => {
+    expect(updateDemoKeyTtl(demoKeys, "cache:homepage", 90_000)[0]?.ttl).toBe("1m");
+    expect(persistDemoKeyTtl(demoKeys, "cache:homepage")[0]?.ttl).toBe("persistent");
+  });
+
+  it("formats preview text and durations consistently", () => {
+    expect(buildDemoStringPreview("alpha beta gamma delta epsilon zeta eta theta", 16)).toBe(
+      "alpha beta gamm…",
+    );
+    expect(formatDemoDurationFromMillis(750)).toBe("750ms");
+    expect(formatDemoDurationFromMillis(5_000)).toBe("5s");
+    expect(formatDemoDurationFromMillis(7_200_000)).toBe("2h");
+    expect(parseDemoTtlToSeconds("750ms")).toBe(0);
+    expect(parseDemoTtlToSeconds("5s")).toBe(5);
+    expect(parseDemoTtlToSeconds("2h")).toBe(7200);
+    expect(parseDemoTtlToSeconds("persistent")).toBe(-1);
+  });
+});

apps/desktop/src/lib/demo-workspace.ts

@@ -0,0 +1,114 @@
+export type DemoWorkspaceKey = {
+  id: string;
+  name: string;
+  type: string;
+  ttl: string;
+  preview: string;
+  editable: boolean;
+  value: string;
+  summary: string;
+};
+
+export function updateDemoStringValue(
+  keys: DemoWorkspaceKey[],
+  keyName: string,
+  value: string,
+) {
+  return keys.map((key) =>
+    key.name === keyName
+      ? {
+          ...key,
+          value,
+          preview: buildDemoStringPreview(value),
+        }
+      : key,
+  );
+}
+
+export function updateDemoKeyTtl(
+  keys: DemoWorkspaceKey[],
+  keyName: string,
+  ttlMillis: number,
+) {
+  return keys.map((key) =>
+    key.name === keyName
+      ? {
+          ...key,
+          ttl: formatDemoDurationFromMillis(ttlMillis),
+        }
+      : key,
+  );
+}
+
+export function persistDemoKeyTtl(keys: DemoWorkspaceKey[], keyName: string) {
+  return keys.map((key) =>
+    key.name === keyName
+      ? {
+          ...key,
+          ttl: "persistent",
+        }
+      : key,
+  );
+}
+
+export function buildDemoStringPreview(value: string, maxLength = 48) {
+  const collapsed = value.replace(/\s+/g, " ").trim();
+  if (collapsed.length <= maxLength) {
+    return collapsed;
+  }
+
+  return `${collapsed.slice(0, maxLength - 1)}…`;
+}
+
+export function formatDemoDurationFromMillis(value: number) {
+  if (value < 1_000) {
+    return `${value}ms`;
+  }
+
+  const totalSeconds = Math.floor(value / 1_000);
+  if (totalSeconds < 60) {
+    return `${totalSeconds}s`;
+  }
+
+  const totalMinutes = Math.floor(totalSeconds / 60);
+  if (totalMinutes < 60) {
+    return `${totalMinutes}m`;
+  }
+
+  const totalHours = Math.floor(totalMinutes / 60);
+  if (totalHours < 24) {
+    return `${totalHours}h`;
+  }
+
+  const totalDays = Math.floor(totalHours / 24);
+  return `${totalDays}d`;
+}
+
+export function parseDemoTtlToSeconds(value: string) {
+  if (value === "persistent") {
+    return -1;
+  }
+
+  const match = value.trim().match(/^(\d+)(ms|s|m|h|d)$/);
+  if (!match) {
+    return 0;
+  }
+
+  const amount = Number.parseInt(match[1], 10);
+  const unit = match[2];
+
+  switch (unit) {
+    case "ms":
+      return Math.floor(amount / 1_000);
+    case "s":
+      return amount;
+    case "m":
+      return amount * 60;
+    case "h":
+      return amount * 60 * 60;
+    case "d":
+      return amount * 60 * 60 * 24;
+    default:
+      return 0;
+  }
+}

apps/desktop/src/lib/inspector-readability.test.ts

@@ -0,0 +1,183 @@
+import { describe, expect, it } from "vitest";
+import { buildInspectorReadabilitySummary } from "./inspector-readability";
+
+describe("inspector readability summary", () => {
+  it("guides the operator when no key is selected", () => {
+    expect(
+      buildInspectorReadabilitySummary({
+        databaseLabel: "db4",
+        runtimeMode: "live",
+        selectedKey: null,
+        record: null,
+        isLoading: false,
+        isEditable: false,
+        ttlWriteSupported: false,
+      }),
+    ).toEqual(
+      expect.objectContaining({
+        status: "awaiting selection",
+        surfaceTitle: "No key selected",
+        actionTitle: "Next step",
+        facts: expect.arrayContaining([
+          { label: "Scope", value: "db4" },
+          { label: "Type", value: "unknown" },
+        ]),
+      }),
+    );
+  });
+
+  it("describes editable live strings with explicit write semantics", () => {
+    expect(
+      buildInspectorReadabilitySummary({
+        databaseLabel: "db0",
+        runtimeMode: "live",
+        selectedKey: {
+          name: "cache:homepage",
+          type: "string",
+          ttl: "48s",
+        },
+        record: {
+          metadata: {
+            key_type: "string",
+            ttl: { kind: "expires_in_millis", value: 48_000 },
+          },
+          data: {
+            kind: "string",
+            value: { kind: "string", value: "payload" },
+          },
+        },
+        isLoading: false,
+        isEditable: true,
+        ttlWriteSupported: true,
+      }),
+    ).toEqual({
+      status: "editable string",
+      surfaceTitle: "String value",
+      surfaceDescription:
+        "The full live string payload is loaded in the inspector. Saving replaces the entire string value and preserves the active TTL boundary.",
+      actionTitle: "Operator path",
+      actionDescription:
+        "Review the full payload, make bounded edits, and use Save string value when you are ready to replace the current value.",
+      facts: [
+        { label: "Scope", value: "db0" },
+        { label: "Type", value: "string" },
+        { label: "TTL state", value: "48s" },
+        { label: "Value shape", value: "string payload" },
+        { label: "Write path", value: "replace full string" },
+        { label: "TTL control", value: "available" },
+      ],
+    });
+  });
+
+  it("describes structured live values as readable inspection-only surfaces", () => {
+    expect(
+      buildInspectorReadabilitySummary({
+        databaseLabel: "db0",
+        runtimeMode: "live",
+        selectedKey: {
+          name: "session:42",
+          type: "hash",
+          ttl: "13m",
+        },
+        record: {
+          metadata: {
+            key_type: "hash",
+            ttl: { kind: "expires_in_millis", value: 780_000 },
+          },
+          data: {
+            kind: "hash",
+            entries: [
+              {
+                field: { kind: "string", value: "region" },
+                value: { kind: "string", value: "eu-west-1" },
+              },
+              {
+                field: { kind: "string", value: "role" },
+                value: { kind: "string", value: "editor" },
+              },
+            ],
+          },
+        },
+        isLoading: false,
+        isEditable: false,
+        ttlWriteSupported: true,
+      }),
+    ).toEqual(
+      expect.objectContaining({
+        status: "structured read only",
+        surfaceTitle: "Hash fields",
+        facts: [
+          { label: "Scope", value: "db0" },
+          { label: "Type", value: "hash" },
+          { label: "TTL state", value: "13m" },
+          { label: "Value shape", value: "2 fields" },
+          { label: "Write path", value: "inspection only" },
+          { label: "TTL control", value: "available" },
+        ],
+      }),
+    );
+  });
+
+  it("keeps demo mode explicit so shell review is not confused with live evidence", () => {
+    expect(
+      buildInspectorReadabilitySummary({
+        databaseLabel: "db0",
+        runtimeMode: "demo",
+        selectedKey: {
+          name: "cache:homepage",
+          type: "string",
+          ttl: "48s",
+        },
+        record: null,
+        isLoading: false,
+        isEditable: true,
+        ttlWriteSupported: true,
+      }),
+    ).toEqual(
+      expect.objectContaining({
+        status: "demo editable",
+        surfaceTitle: "String value",
+        facts: expect.arrayContaining([
+          { label: "Write path", value: "session-local string save" },
+          { label: "TTL control", value: "available" },
+        ]),
+      }),
+    );
+  });
+
+  it("makes stale browse-to-read gaps explicit when the key disappears", () => {
+    expect(
+      buildInspectorReadabilitySummary({
+        databaseLabel: "db2",
+        runtimeMode: "live",
+        selectedKey: {
+          name: "jobs:failed",
+          type: "list",
+          ttl: "persistent",
+        },
+        record: {
+          metadata: {
+            key_type: "list",
+            ttl: { kind: "missing" },
+          },
+          data: {
+            kind: "missing",
+          },
+        },
+        isLoading: false,
+        isEditable: false,
+        ttlWriteSupported: false,
+      }),
+    ).toEqual(
+      expect.objectContaining({
+        status: "missing key",
+        surfaceTitle: "Key disappeared after browse",
+        facts: expect.arrayContaining([
+          { label: "Scope", value: "db2" },
+          { label: "TTL state", value: "missing" },
+          { label: "Write path", value: "not available" },
+        ]),
+      }),
+    );
+  });
+});

apps/desktop/src/lib/inspector-readability.ts

@@ -0,0 +1,340 @@
+type RedisKeyTtl =
+  | { kind: "persistent" }
+  | { kind: "missing" }
+  | { kind: "expires_in_millis"; value: number };
+
+type RedisValueContent =
+  | { kind: "string"; value: string }
+  | { kind: "binary"; bytes: number[] };
+
+type RedisFieldValueEntry = {
+  field: RedisValueContent;
+  value: RedisValueContent;
+};
+
+type RedisSortedSetEntry = {
+  member: RedisValueContent;
+  score: string;
+};
+
+type RedisStreamEntry = {
+  id: string;
+  fields: RedisFieldValueEntry[];
+};
+
+type RedisValueData =
+  | { kind: "missing" }
+  | { kind: "string"; value: RedisValueContent }
+  | { kind: "hash"; entries: RedisFieldValueEntry[] }
+  | { kind: "list"; items: RedisValueContent[] }
+  | { kind: "set"; members: RedisValueContent[] }
+  | { kind: "sorted_set"; entries: RedisSortedSetEntry[] }
+  | { kind: "stream"; entries: RedisStreamEntry[] };
+
+type RedisValueRecord = {
+  metadata: {
+    key_type: string;
+    ttl: RedisKeyTtl;
+  };
+  data: RedisValueData;
+};
+
+type SelectedInspectorKey = {
+  name: string;
+  type: string;
+  ttl: string;
+};
+
+export type InspectorFact = {
+  label: string;
+  value: string;
+};
+
+export type InspectorReadabilitySummary = {
+  status: string;
+  surfaceTitle: string;
+  surfaceDescription: string;
+  actionTitle: string;
+  actionDescription: string;
+  facts: InspectorFact[];
+};
+
+export type InspectorReadabilityContext = {
+  databaseLabel: string;
+  runtimeMode: "live" | "demo";
+  selectedKey: SelectedInspectorKey | null;
+  record: RedisValueRecord | null;
+  isLoading: boolean;
+  isEditable: boolean;
+  ttlWriteSupported: boolean;
+};
+
+export function buildInspectorReadabilitySummary(
+  context: InspectorReadabilityContext,
+): InspectorReadabilitySummary {
+  const keyType = resolveKeyType(context);
+  const ttlState = resolveTtlState(context);
+  const valueShape = describeValueShape(context);
+  const writePath = describeWritePath(context);
+  const ttlPath = context.selectedKey
+    ? context.ttlWriteSupported
+      ? "available"
+      : "not available"
+    : "awaiting selection";
+  const facts: InspectorFact[] = [
+    { label: "Scope", value: context.databaseLabel },
+    { label: "Type", value: formatRedisKeyTypeLabel(keyType) },
+    { label: "TTL state", value: ttlState },
+    { label: "Value shape", value: valueShape },
+    { label: "Write path", value: writePath },
+    { label: "TTL control", value: ttlPath },
+  ];
+
+  if (!context.selectedKey) {
+    return {
+      status: "awaiting selection",
+      surfaceTitle: "No key selected",
+      surfaceDescription:
+        "Pick a key from the browser to load its metadata, value shape, and TTL state into the inspector.",
+      actionTitle: "Next step",
+      actionDescription:
+        "If the browser is empty, clear or adjust the current search so the inspector has a live target again.",
+      facts,
+    };
+  }
+
+  if (context.runtimeMode === "demo") {
+    return {
+      status: context.isEditable ? "demo editable" : "demo read only",
+      surfaceTitle: buildSurfaceTitle(context.selectedKey.type, false),
+      surfaceDescription: context.isEditable
+        ? "Browser dev mode is showing a session-local string payload. Layout review is safe here, but no live Redis mutation occurs."
+        : `${formatRedisKeyTypeLabel(context.selectedKey.type)} payloads stay on the demo inspection path in browser mode so the UI can be reviewed without pretending a live backend exists.`,
+      actionTitle: "Operator path",
+      actionDescription: context.isEditable
+        ? "Use Save string value only for session-local shell review. Switch to the desktop runtime before treating the result as Redis evidence."
+        : "Review the current structure here, then use the desktop runtime when you need live Redis data or verification.",
+      facts,
+    };
+  }
+
+  if (context.isLoading) {
+    return {
+      status: "loading",
+      surfaceTitle: `Loading ${formatRedisKeyTypeLabel(keyType)} value`,
+      surfaceDescription:
+        "The desktop bridge is reading the current key so the inspector can show live metadata, value shape, and write capability together.",
+      actionTitle: "Operator path",
+      actionDescription:
+        "Wait for the read to finish before editing or relying on the TTL state shown in the inspector.",
+      facts,
+    };
+  }
+
+  if (!context.record) {
+    return {
+      status: "metadata only",
+      surfaceTitle: `${formatRedisKeyTypeLabel(keyType)} metadata ready`,
+      surfaceDescription:
+        "The browser still has metadata for the selected key, but the live value surface is not currently loaded in the inspector.",
+      actionTitle: "Operator path",
+      actionDescription:
+        "Use Refresh metadata to retry the live read, or return to the browser if the key may have changed upstream.",
+      facts,
+    };
+  }
+
+  if (context.record.data.kind === "missing") {
+    return {
+      status: "missing key",
+      surfaceTitle: "Key disappeared after browse",
+      surfaceDescription:
+        "The key was visible during browse but no longer existed when the inspector requested the live value.",
+      actionTitle: "Operator path",
+      actionDescription:
+        "Refresh metadata or reload the browser list to clear the stale selection before taking further action.",
+      facts,
+    };
+  }
+
+  if (context.isEditable) {
+    return {
+      status: "editable string",
+      surfaceTitle: "String value",
+      surfaceDescription:
+        "The full live string payload is loaded in the inspector. Saving replaces the entire string value and preserves the active TTL boundary.",
+      actionTitle: "Operator path",
+      actionDescription:
+        "Review the full payload, make bounded edits, and use Save string value when you are ready to replace the current value.",
+      facts,
+    };
+  }
+
+  return {
+    status: "structured read only",
+    surfaceTitle: buildSurfaceTitle(context.record.data.kind, true),
+    surfaceDescription: buildStructuredDescription(context.record.data.kind),
+    actionTitle: "Operator path",
+    actionDescription:
+      "Use the structured panels to scan the live payload quickly. Mutations for this key type remain outside the current desktop contract.",
+    facts,
+  };
+}
+
+function resolveKeyType(context: InspectorReadabilityContext) {
+  return context.record?.metadata.key_type ?? context.selectedKey?.type ?? "unknown";
+}
+
+function resolveTtlState(context: InspectorReadabilityContext) {
+  if (context.record) {
+    return formatRedisKeyTtl(context.record.metadata.ttl);
+  }
+
+  return context.selectedKey?.ttl ?? "awaiting selection";
+}
+
+function describeValueShape(context: InspectorReadabilityContext) {
+  if (!context.selectedKey) {
+    return "no active key";
+  }
+
+  if (context.runtimeMode === "demo") {
+    return context.isEditable
+      ? "session-local string payload"
+      : `${formatRedisKeyTypeLabel(context.selectedKey.type)} demo preview`;
+  }
+
+  if (context.isLoading) {
+    return "live value request in flight";
+  }
+
+  if (!context.record) {
+    return "metadata loaded, value unavailable";
+  }
+
+  switch (context.record.data.kind) {
+    case "missing":
+      return "key missing";
+    case "string":
+      return "string payload";
+    case "hash":
+      return `${context.record.data.entries.length} field${context.record.data.entries.length === 1 ? "" : "s"}`;
+    case "list":
+      return `${context.record.data.items.length} item${context.record.data.items.length === 1 ? "" : "s"}`;
+    case "set":
+      return `${context.record.data.members.length} member${context.record.data.members.length === 1 ? "" : "s"}`;
+    case "sorted_set":
+      return `${context.record.data.entries.length} scored member${context.record.data.entries.length === 1 ? "" : "s"}`;
+    case "stream":
+      return `${context.record.data.entries.length} entr${context.record.data.entries.length === 1 ? "y" : "ies"}`;
+    default:
+      return "unknown";
+  }
+}
+
+function describeWritePath(context: InspectorReadabilityContext) {
+  if (!context.selectedKey) {
+    return "awaiting selection";
+  }
+
+  if (context.runtimeMode === "demo") {
+    return context.isEditable ? "session-local string save" : "inspection only";
+  }
+
+  if (context.isLoading) {
+    return "pending live capability";
+  }
+
+  if (!context.record) {
+    return "value unavailable";
+  }
+
+  if (context.record.data.kind === "missing") {
+    return "not available";
+  }
+
+  return context.isEditable ? "replace full string" : "inspection only";
+}
+
+function buildSurfaceTitle(kind: string, liveStructured: boolean) {
+  switch (kind) {
+    case "hash":
+      return "Hash fields";
+    case "list":
+      return "List items";
+    case "set":
+      return liveStructured ? "Set members" : "Set preview";
+    case "sorted_set":
+    case "zset":
+      return "Sorted set members";
+    case "stream":
+      return "Stream entries";
+    case "string":
+      return "String value";
+    default:
+      return "Value surface";
+  }
+}
+
+function buildStructuredDescription(kind: string) {
+  switch (kind) {
+    case "hash":
+      return "Live HGETALL output is rendered as field/value rows so operators do not need to parse raw JSON during inspection.";
+    case "list":
+      return "Live LRANGE output is rendered in list order so operators can scan indexed items without leaving the inspector.";
+    case "set":
+      return "Live SMEMBERS output is rendered as a structured member list so the inspector stays readable even when the payload is dense.";
+    case "sorted_set":
+      return "Live ZRANGE output is rendered as member and score pairs so ordering semantics stay visible in the inspector.";
+    case "stream":
+      return "Live XRANGE output is rendered as entry rows with inline field payloads so stream structure is visible at a glance.";
+    default:
+      return "The live value is available on a structured read-only path in the current desktop contract.";
+  }
+}
+
+function formatRedisKeyTtl(ttl: RedisKeyTtl) {
+  switch (ttl.kind) {
+    case "persistent":
+      return "persistent";
+    case "missing":
+      return "missing";
+    case "expires_in_millis":
+      return formatDurationFromMillis(ttl.value);
+    default:
+      return "unknown";
+  }
+}
+
+function formatDurationFromMillis(value: number) {
+  if (value < 1_000) {
+    return `${value}ms`;
+  }
+
+  const totalSeconds = Math.floor(value / 1_000);
+  if (totalSeconds < 60) {
+    return `${totalSeconds}s`;
+  }
+
+  const totalMinutes = Math.floor(totalSeconds / 60);
+  if (totalMinutes < 60) {
+    return `${totalMinutes}m`;
+  }
+
+  const totalHours = Math.floor(totalMinutes / 60);
+  if (totalHours < 24) {
+    return `${totalHours}h`;
+  }
+
+  const totalDays = Math.floor(totalHours / 24);
+  return `${totalDays}d`;
+}
+
+function formatRedisKeyTypeLabel(value: string) {
+  switch (value) {
+    case "zset":
+      return "sorted set";
+    default:
+      return value || "unknown";
+  }
+}

apps/desktop/src/lib/key-browser-search.test.ts

@@ -0,0 +1,83 @@
+import { describe, expect, it } from "vitest";
+import {
+  buildInspectorEmptyStateMessage,
+  buildKeyBrowserEmptyStateMessage,
+  buildKeyBrowserStatusMessage,
+  resolveKeyBrowserSearchState,
+} from "./key-browser-search";
+
+describe("key browser search helpers", () => {
+  it("classifies blank, contains, and wildcard search input", () => {
+    expect(resolveKeyBrowserSearchState("   ")).toEqual({
+      trimmedQuery: "",
+      requestPattern: null,
+      mode: "all",
+    });
+
+    expect(resolveKeyBrowserSearchState(" smoke ")).toEqual({
+      trimmedQuery: "smoke",
+      requestPattern: "*smoke*",
+      mode: "contains",
+    });
+
+    expect(resolveKeyBrowserSearchState("smoke:*")).toEqual({
+      trimmedQuery: "smoke:*",
+      requestPattern: "smoke:*",
+      mode: "pattern",
+    });
+  });
+
+  it("builds a stable status message for visible counts and load state", () => {
+    expect(
+      buildKeyBrowserStatusMessage({
+        databaseLabel: "db0",
+        visibleCount: 7,
+        hasMore: true,
+        isLoading: false,
+        search: resolveKeyBrowserSearchState("smoke"),
+      }),
+    ).toBe('7+ keys visible for contains search "smoke" in db0.');
+
+    expect(
+      buildKeyBrowserStatusMessage({
+        databaseLabel: "db3",
+        visibleCount: 0,
+        hasMore: false,
+        isLoading: true,
+        search: resolveKeyBrowserSearchState("smoke:*"),
+      }),
+    ).toBe('Searching db3 for "smoke:*".');
+  });
+
+  it("builds browser empty-state copy for blank and filtered results", () => {
+    expect(
+      buildKeyBrowserEmptyStateMessage({
+        databaseLabel: "db0",
+        isLoading: false,
+        search: resolveKeyBrowserSearchState(""),
+      }),
+    ).toBe("No keys are visible in db0 yet.");
+
+    expect(
+      buildKeyBrowserEmptyStateMessage({
+        databaseLabel: "db2",
+        isLoading: false,
+        search: resolveKeyBrowserSearchState("audit:*"),
+      }),
+    ).toBe('No keys match "audit:*" in db2.');
+  });
+
+  it("keeps inspector empty-state guidance aligned with browser search state", () => {
+    expect(
+      buildInspectorEmptyStateMessage("db1", resolveKeyBrowserSearchState("")),
+    ).toBe(
+      "No keys are visible in db1 yet. Browse another database or refresh after data arrives.",
+    );
+
+    expect(
+      buildInspectorEmptyStateMessage("db4", resolveKeyBrowserSearchState("jobs")),
+    ).toBe(
+      'No keys match "jobs" in db4. Clear or adjust the search to restore an inspector target.',
+    );
+  });
+});

apps/desktop/src/lib/key-browser-search.ts

@@ -0,0 +1,100 @@
+export type KeyBrowserSearchMode = "all" | "contains" | "pattern";
+
+export type KeyBrowserSearchState = {
+  trimmedQuery: string;
+  requestPattern: string | null;
+  mode: KeyBrowserSearchMode;
+};
+
+type KeyBrowserFeedbackContext = {
+  databaseLabel: string;
+  visibleCount: number;
+  hasMore: boolean;
+  isLoading: boolean;
+  search: KeyBrowserSearchState;
+};
+
+export function resolveKeyBrowserSearchState(value: string): KeyBrowserSearchState {
+  const trimmedQuery = value.trim();
+  if (!trimmedQuery) {
+    return {
+      trimmedQuery: "",
+      requestPattern: null,
+      mode: "all",
+    };
+  }
+
+  if (/[*?\[\]]/.test(trimmedQuery)) {
+    return {
+      trimmedQuery,
+      requestPattern: trimmedQuery,
+      mode: "pattern",
+    };
+  }
+
+  return {
+    trimmedQuery,
+    requestPattern: `*${trimmedQuery}*`,
+    mode: "contains",
+  };
+}
+
+export function buildKeyBrowserStatusMessage({
+  databaseLabel,
+  visibleCount,
+  hasMore,
+  isLoading,
+  search,
+}: KeyBrowserFeedbackContext) {
+  if (isLoading) {
+    if (search.mode === "all") {
+      return `Loading keys from ${databaseLabel}.`;
+    }
+
+    return `Searching ${databaseLabel} for ${formatSearchLabel(search)}.`;
+  }
+
+  const visibleLabel = `${visibleCount}${hasMore ? "+" : ""}`;
+
+  if (search.mode === "all") {
+    return `${visibleLabel} keys visible in ${databaseLabel}.`;
+  }
+
+  const searchLabel =
+    search.mode === "pattern"
+      ? `pattern ${formatSearchLabel(search)}`
+      : `contains search ${formatSearchLabel(search)}`;
+
+  return `${visibleLabel} keys visible for ${searchLabel} in ${databaseLabel}.`;
+}
+
+export function buildKeyBrowserEmptyStateMessage({
+  databaseLabel,
+  isLoading,
+  search,
+}: Omit<KeyBrowserFeedbackContext, "visibleCount" | "hasMore">) {
+  if (isLoading) {
+    return `Loading keys from ${databaseLabel}...`;
+  }
+
+  if (search.mode === "all") {
+    return `No keys are visible in ${databaseLabel} yet.`;
+  }
+
+  return `No keys match ${formatSearchLabel(search)} in ${databaseLabel}.`;
+}
+
+export function buildInspectorEmptyStateMessage(
+  databaseLabel: string,
+  search: KeyBrowserSearchState,
+) {
+  if (search.mode === "all") {
+    return `No keys are visible in ${databaseLabel} yet. Browse another database or refresh after data arrives.`;
+  }
+
+  return `No keys match ${formatSearchLabel(search)} in ${databaseLabel}. Clear or adjust the search to restore an inspector target.`;
+}
+
+function formatSearchLabel(search: KeyBrowserSearchState) {
+  return `"${search.trimmedQuery}"`;
+}

apps/desktop/src/lib/key-workspace-state.test.ts

@@ -0,0 +1,105 @@
+import { describe, expect, it } from "vitest";
+import {
+  appendWorkspaceKeyRecords,
+  filterWorkspaceKeys,
+  replaceWorkspaceKeyRecord,
+  resolveSelectedWorkspaceKey,
+  resolveSelectedWorkspaceKeyId,
+} from "./key-workspace-state";
+
+const workspaceKeys = [
+  {
+    id: "session:42",
+    name: "session:42",
+    ttl: "13m",
+    preview: "hash value",
+  },
+  {
+    id: "cache:homepage",
+    name: "cache:homepage",
+    ttl: "48s",
+    preview: "string value",
+  },
+];
+
+describe("key workspace state helpers", () => {
+  it("filters keys by name using trimmed case-insensitive search", () => {
+    expect(filterWorkspaceKeys(workspaceKeys, "  CACHE ")).toEqual([
+      workspaceKeys[1],
+    ]);
+    expect(filterWorkspaceKeys(workspaceKeys, "   ")).toEqual(workspaceKeys);
+  });
+
+  it("resolves the selected key and falls back to the first visible key", () => {
+    expect(resolveSelectedWorkspaceKey(workspaceKeys, "cache:homepage")).toEqual(
+      workspaceKeys[1],
+    );
+    expect(resolveSelectedWorkspaceKey(workspaceKeys, "missing")).toEqual(
+      workspaceKeys[0],
+    );
+    expect(resolveSelectedWorkspaceKey([], "missing")).toBeNull();
+  });
+
+  it("resolves the selected key id for list refresh flows", () => {
+    expect(resolveSelectedWorkspaceKeyId(workspaceKeys, "cache:homepage")).toBe(
+      "cache:homepage",
+    );
+    expect(resolveSelectedWorkspaceKeyId(workspaceKeys, "missing")).toBe(
+      "session:42",
+    );
+    expect(resolveSelectedWorkspaceKeyId([], "missing")).toBeNull();
+  });
+
+  it("replaces an existing key while preserving untouched fields", () => {
+    expect(
+      replaceWorkspaceKeyRecord(workspaceKeys, {
+        id: "cache:homepage",
+        name: "cache:homepage",
+        ttl: "persistent",
+      }),
+    ).toEqual([
+      workspaceKeys[0],
+      {
+        ...workspaceKeys[1],
+        ttl: "persistent",
+      },
+    ]);
+  });
+
+  it("prepends unseen replacements and appends only new paged keys", () => {
+    expect(
+      replaceWorkspaceKeyRecord(workspaceKeys, {
+        id: "smoke:string",
+        name: "smoke:string",
+        ttl: "5m",
+      }),
+    ).toEqual([
+      {
+        id: "smoke:string",
+        name: "smoke:string",
+        ttl: "5m",
+      },
+      ...workspaceKeys,
+    ]);
+
+    expect(
+      appendWorkspaceKeyRecords(workspaceKeys, [
+        workspaceKeys[1],
+        {
+          id: "smoke:string",
+          name: "smoke:string",
+          ttl: "5m",
+          preview: "fixture key",
+        },
+      ]),
+    ).toEqual([
+      ...workspaceKeys,
+      {
+        id: "smoke:string",
+        name: "smoke:string",
+        ttl: "5m",
+        preview: "fixture key",
+      },
+    ]);
+  });
+});

apps/desktop/src/lib/key-workspace-state.ts

@@ -0,0 +1,76 @@
+export type WorkspaceKeyIdentity = {
+  id: string;
+};
+
+export type WorkspaceSearchableKey = WorkspaceKeyIdentity & {
+  name: string;
+};
+
+export function filterWorkspaceKeys<T extends WorkspaceSearchableKey>(
+  keys: T[],
+  search: string,
+) {
+  const query = search.trim().toLowerCase();
+  if (!query) {
+    return keys;
+  }
+
+  return keys.filter((item) => item.name.toLowerCase().includes(query));
+}
+
+export function resolveSelectedWorkspaceKey<T extends WorkspaceKeyIdentity>(
+  keys: T[],
+  selectedKeyId: string | null,
+) {
+  if (keys.length === 0) {
+    return null;
+  }
+
+  return keys.find((item) => item.id === selectedKeyId) ?? keys[0];
+}
+
+export function resolveSelectedWorkspaceKeyId<T extends WorkspaceKeyIdentity>(
+  keys: T[],
+  selectedKeyId: string | null,
+) {
+  return resolveSelectedWorkspaceKey(keys, selectedKeyId)?.id ?? null;
+}
+
+export function replaceWorkspaceKeyRecord<T extends WorkspaceKeyIdentity>(
+  current: T[],
+  next: T,
+) {
+  let replaced = false;
+  const updated = current.map((item) => {
+    if (item.id !== next.id) {
+      return item;
+    }
+
+    replaced = true;
+    return {
+      ...item,
+      ...next,
+    };
+  });
+
+  return replaced ? updated : [next, ...current];
+}
+
+export function appendWorkspaceKeyRecords<T extends WorkspaceKeyIdentity>(
+  current: T[],
+  next: T[],
+) {
+  const seen = new Set(current.map((item) => item.id));
+  const appended = [...current];
+
+  for (const item of next) {
+    if (seen.has(item.id)) {
+      continue;
+    }
+
+    seen.add(item.id);
+    appended.push(item);
+  }
+
+  return appended;
+}

apps/desktop/src/lib/local-smoke-fixture.test.ts

@@ -0,0 +1,55 @@
+import { describe, expect, it } from "vitest";
+import {
+  isLocalSmokeFixtureConnection,
+  localSmokeFixtureCommandPresets,
+  localSmokeFixtureExpectedKeys,
+  localSmokeFixtureProfileId,
+  localSmokeFixtureSearchText,
+} from "./local-smoke-fixture";
+
+describe("local smoke fixture helpers", () => {
+  it("keeps the expected local smoke verification targets stable", () => {
+    expect(localSmokeFixtureProfileId).toBe("redis-local-fixture");
+    expect(localSmokeFixtureSearchText).toBe("smoke:*");
+    expect(localSmokeFixtureExpectedKeys).toEqual([
+      "smoke:string",
+      "smoke:string:ttl",
+      "smoke:hash",
+      "smoke:list",
+      "smoke:set",
+      "smoke:zset",
+      "smoke:stream",
+    ]);
+  });
+
+  it("detects the built-in local fixture profile by id or target", () => {
+    expect(
+      isLocalSmokeFixtureConnection({
+        id: "redis-local-fixture",
+        target: { host: "10.0.0.1", port: 6379, database: 2 },
+      }),
+    ).toBe(true);
+
+    expect(
+      isLocalSmokeFixtureConnection({
+        id: "custom-profile",
+        target: { host: "127.0.0.1", port: 6380, database: 0 },
+      }),
+    ).toBe(true);
+
+    expect(
+      isLocalSmokeFixtureConnection({
+        id: "redis-local-fixture",
+        target: { host: "127.0.0.1", port: 6380, database: 1 },
+      }),
+    ).toBe(true);
+  });
+
+  it("keeps fixture quick commands on a safe read-only path", () => {
+    expect(localSmokeFixtureCommandPresets.map((preset) => preset.command)).toEqual([
+      "PING",
+      "GET smoke:string",
+      "TTL smoke:string:ttl",
+    ]);
+  });
+});

apps/desktop/src/lib/local-smoke-fixture.ts

@@ -0,0 +1,53 @@
+export const localSmokeFixtureProfileId = "redis-local-fixture";
+export const localSmokeFixtureSearchText = "smoke:*";
+
+export const localSmokeFixtureExpectedKeys = [
+  "smoke:string",
+  "smoke:string:ttl",
+  "smoke:hash",
+  "smoke:list",
+  "smoke:set",
+  "smoke:zset",
+  "smoke:stream",
+] as const;
+
+export const localSmokeFixtureCommandPresets = [
+  {
+    id: "ping",
+    label: "PING",
+    command: "PING",
+    summary: "Validate the desktop command bridge against the seeded fixture.",
+  },
+  {
+    id: "get-string",
+    label: "GET smoke:string",
+    command: "GET smoke:string",
+    summary: "Verify the string read path against the seeded smoke key.",
+  },
+  {
+    id: "ttl-string",
+    label: "TTL smoke:string:ttl",
+    command: "TTL smoke:string:ttl",
+    summary: "Verify the TTL path before using the inspector controls.",
+  },
+] as const;
+
+type LocalSmokeFixtureTarget = {
+  id: string;
+  target: {
+    host: string;
+    port: number;
+    database: number;
+  };
+};
+
+export function isLocalSmokeFixtureConnection(
+  connection: LocalSmokeFixtureTarget,
+) {
+  return (
+    connection.id === localSmokeFixtureProfileId ||
+    (connection.target.host === "127.0.0.1" &&
+      connection.target.port === 6380 &&
+      connection.target.database === 0)
+  );
+}

apps/desktop/src/lib/qa-snapshot.test.ts

@@ -0,0 +1,72 @@
+import { describe, expect, it } from "vitest";
+import { buildQaSnapshot } from "./qa-snapshot";
+
+describe("qa snapshot", () => {
+  it("serializes the current smoke context into a stable line-oriented summary", () => {
+    expect(
+      buildQaSnapshot({
+        appName: "Redis GUI Foundation",
+        appVersion: "0.1.0",
+        runtimeMode: "live desktop bridge",
+        buildMode: "production",
+        connectionName: "redis-local-fixture",
+        endpoint: "127.0.0.1:6380",
+        databaseLabel: "db0",
+        smokeFixtureActive: true,
+        smokeFilter: "smoke:*",
+        selectedKeyName: "smoke:string",
+        selectedKeyType: "string",
+        selectedKeyTtl: "persistent",
+        browseVisibleCount: "7",
+        latestCommand: "PING",
+        latestCommandSource: "live",
+        latestCommandStatus: "ok",
+        bannerMessage: "Copied the current QA snapshot to the clipboard for smoke evidence.",
+      }),
+    ).toEqual(
+      [
+        "app=Redis GUI Foundation",
+        "version=0.1.0",
+        "runtime=live desktop bridge",
+        "build=production",
+        "connection=redis-local-fixture",
+        "endpoint=127.0.0.1:6380",
+        "database=db0",
+        "smokeFixtureActive=yes",
+        "smokeFilter=smoke:*",
+        "selectedKey=smoke:string",
+        "selectedType=string",
+        "selectedTtl=persistent",
+        "browseVisible=7",
+        "latestCommand=PING",
+        "latestCommandSource=live",
+        "latestCommandStatus=ok",
+        "banner=Copied the current QA snapshot to the clipboard for smoke evidence.",
+      ].join("\n"),
+    );
+  });
+
+  it("normalizes empty or missing values so smoke logs stay readable", () => {
+    expect(
+      buildQaSnapshot({
+        appName: "Redis GUI Foundation",
+        appVersion: "0.1.0",
+        runtimeMode: "browser demo fallback",
+        buildMode: "dev",
+        connectionName: "redis-dev-eu-1",
+        endpoint: "127.0.0.1:6379",
+        databaseLabel: "db1",
+        smokeFixtureActive: false,
+        smokeFilter: "   ",
+        selectedKeyName: null,
+        selectedKeyType: null,
+        selectedKeyTtl: null,
+        browseVisibleCount: "0",
+        latestCommand: null,
+        latestCommandSource: null,
+        latestCommandStatus: null,
+        bannerMessage: "No key matches the current pattern.",
+      }),
+    ).toContain("smokeFilter=none");
+  });
+});

apps/desktop/src/lib/qa-snapshot.ts

@@ -0,0 +1,41 @@
+export type QaSnapshotInput = {
+  appName: string;
+  appVersion: string;
+  runtimeMode: string;
+  buildMode: string;
+  connectionName: string;
+  endpoint: string;
+  databaseLabel: string;
+  smokeFixtureActive: boolean;
+  smokeFilter: string;
+  selectedKeyName: string | null;
+  selectedKeyType: string | null;
+  selectedKeyTtl: string | null;
+  browseVisibleCount: string;
+  latestCommand: string | null;
+  latestCommandSource: string | null;
+  latestCommandStatus: string | null;
+  bannerMessage: string;
+};
+
+export function buildQaSnapshot(input: QaSnapshotInput) {
+  return [
+    `app=${input.appName}`,
+    `version=${input.appVersion}`,
+    `runtime=${input.runtimeMode}`,
+    `build=${input.buildMode}`,
+    `connection=${input.connectionName}`,
+    `endpoint=${input.endpoint}`,
+    `database=${input.databaseLabel}`,
+    `smokeFixtureActive=${input.smokeFixtureActive ? "yes" : "no"}`,
+    `smokeFilter=${input.smokeFilter.trim() || "none"}`,
+    `selectedKey=${input.selectedKeyName ?? "none"}`,
+    `selectedType=${input.selectedKeyType ?? "none"}`,
+    `selectedTtl=${input.selectedKeyTtl ?? "none"}`,
+    `browseVisible=${input.browseVisibleCount}`,
+    `latestCommand=${input.latestCommand ?? "none"}`,
+    `latestCommandSource=${input.latestCommandSource ?? "none"}`,
+    `latestCommandStatus=${input.latestCommandStatus ?? "none"}`,
+    `banner=${input.bannerMessage}`,
+  ].join("\n");
+}

docs/frontend-workspace-baseline.md

@@ -91,6 +91,7 @@ Use a four-zone workspace:
 - The visible shell now validates draft-connection name, host, port, and DB input before creation, and prevents duplicate profile names inside the local shell state.
 - Zero-result key searches now place the inspector into an explicit empty state instead of leaving a stale key visible.
 - Frontend error handling now routes stable backend error codes through a shared operator-facing notice layer so live failures render with consistent copy and banner tone across connection, browse, inspect, write, TTL, and command flows.
+- The inspector now also renders a dedicated readability layer with explicit inspect status, value-surface semantics, next-step guidance, and key facts so string, structured, missing, and demo-fallback states are easier to interpret.
 
 ## QA Acceptance For This Milestone
 
@@ -105,6 +106,7 @@ Use a four-zone workspace:
 - Live backend failures are shown through a consistent banner treatment instead of per-surface ad hoc copy.
 - Non-string keys are explicitly read-only.
 - Non-string keys render as structured typed panels instead of raw JSON text blobs.
+- The inspector keeps current status, value semantics, action guidance, and key facts visible without requiring operators to infer meaning from badges or raw payload shape alone.
 - String keys show a save affordance near the value surface.
 - TTL controls stay beside the inspector metadata and expose both set and remove flows.
 - Delete requires a second confirmation step that includes key name and DB context.

docs/qa/acceptance-matrix.md

@@ -6,6 +6,7 @@ Owner: QA Engineer
 ## Evidence Collected On 2026-03-27
 
 - A fresh `cargo test -p redis-core` rerun passes in this session with 16 tests green.
+- `pnpm --filter @redis-gui/desktop test` passes in this session with 8 files and 30 tests green.
 - `pnpm install --lockfile-only` passes at repository root after adding `pnpm-workspace.yaml`.
 - `pnpm run desktop:build` passes and emits `apps/desktop/dist/`.
 - `pnpm run desktop:tauri:build` now completes Linux `.deb` and `.rpm` artifact generation under `target/release/bundle/`, then fails later in the AppImage stage with `io: Connection reset by peer (os error 104)`.
@@ -20,11 +21,11 @@ Owner: QA Engineer
 | Linux app smoke | App installs or launches from a documented command, opens main window, connects to test Redis, exits cleanly | Missing Redis, bad host, bad password, unsupported DB or network loss surface actionable error and app stays stable | Launch steps, versioned artifact or dev command, screenshots, QA run log | Partially blocked: documented fixture and smoke path now exist, but a full Linux launch-and-connect evidence set is still pending |
 | macOS app smoke | Same as Linux, using signed or documented macOS artifact | Same failure paths, plus first-run permission or gatekeeper guidance if relevant | Build artifact name, install steps, screenshots, QA run log | Blocked: no validated macOS build or artifact evidence |
 | Windows app smoke | Same as Linux, using installer or portable package | Same failure paths, plus Windows-specific install and uninstall validation | Build artifact name, install steps, screenshots, QA run log | Blocked: no validated Windows build or artifact evidence |
-| Desktop workspace shell | Rail, browser, inspector, and command tray render together with active connection, build identity, runtime mode, and a copyable QA snapshot visible; command history labels live vs demo results | Empty search state clears the inspector selection, read-only non-string value state, destructive confirmation, and browser-mode demo fallback stay stable and explicit | `npm run desktop:dev` or `npm run desktop:build`, `docs/frontend-workspace-baseline.md`, screenshots or copied QA snapshot text | Pass for shell-level evidence; not a substitute for Redis feature acceptance |
+| Desktop workspace shell | Rail, browser, inspector, and command tray render together with active connection, build identity, runtime mode, and a copyable QA snapshot visible; command history labels live vs demo results; inspector summary and key facts stay visible for the active key | Empty search state clears the inspector selection, read-only non-string value state, inspector status/action guidance stays aligned to live vs demo vs missing cases, destructive confirmation, and browser-mode demo fallback stay stable and explicit | `npm run desktop:dev` or `npm run desktop:build`, `docs/frontend-workspace-baseline.md`, screenshots or copied QA snapshot text | Pass for shell-level evidence; not a substitute for Redis feature acceptance |
 | Connection management | Create a validated draft profile, keep DB context visible, and run the existing live connection-test bridge from Tauri desktop mode | Invalid host, bad port, bad password, duplicate name, timeout, and unreachable server are handled with consistent operator-facing messaging | Tauri run log, screenshots, repeatable steps, Redis target | Partially blocked: the shell now validates draft name/host/port/DB locally, maps backend error codes into shared notices, and calls the real connection-test command, but profile persistence and full evidence capture are not complete |
 | Key browsing | Browse DBs and keys, paginate or virtualize large lists, view metadata | Empty DB, deleted key during browse, permission error, and connection drop do not crash UI, and live failures reuse the shared error banner treatment | Seed dataset, result screenshots, observed limits | Partially blocked: desktop UI now calls the live browse bridge with `SCAN` pagination and metadata, but fixture-backed Tauri screenshots and measured limits are still pending |
 | Search | Search by key name or pattern and return matching set within documented limits | No matches, invalid pattern, and very large result sets are handled predictably | Seed dataset, search queries, measured behavior | Partially blocked: desktop UI now maps search to live browse requests, but fixture-backed evidence and measured limits are still pending |
-| Value editing | Open supported value types, edit, save, and refresh persisted value | Concurrent modification, invalid payload, and permission error preserve user context and surface failure through the shared operator notice layer | Before/after values, screenshots, repeatable steps | Partially blocked: string read/save/refresh is wired through the live desktop bridge, and non-string types now render in structured read-only inspector panels, but fixture-backed evidence and broader editing scope remain pending |
+| Value editing | Open supported value types, edit, save, and refresh persisted value; inspector keeps current state and write semantics explicit while editing | Concurrent modification, invalid payload, missing-key transitions, and permission error preserve user context and surface failure through the shared operator notice layer | Before/after values, screenshots, repeatable steps | Partially blocked: string read/save/refresh is wired through the live desktop bridge, non-string types now render in structured read-only inspector panels, and the inspector guidance is clearer across live and fallback states, but fixture-backed evidence and broader editing scope remain pending |
 | TTL operations | View TTL, set TTL, remove TTL, and verify expiration behavior | Invalid TTL, already expired key, and permission error handled safely with consistent banner feedback | Seed dataset, timestamps, verification steps | Partially blocked: desktop UI now exposes live TTL set and remove controls through the existing contract, but seeded-fixture validation evidence is still missing |
 | Command console | Execute safe Redis commands in Tauri desktop mode and show result or error output with explicit live/demo labeling | Invalid command, long-running command, and blocked dangerous command are handled predictably, and backend failures reuse the shared operator notice mapping | Command transcript, screenshots, allow or deny rules | Partially blocked: the desktop UI now calls the real command execution bridge, but it is not yet validated against a shared live Redis fixture and dangerous mutations still stay blocked at shell level |
 | Dangerous operation confirmation | Delete, flush, overwrite, or destructive commands require explicit confirmation | Cancel path does not mutate data; confirm path mutates only intended scope | Confirmation UX screenshots, before/after data | Blocked: feature not implemented |

docs/qa/local-desktop-smoke.md

@@ -73,7 +73,7 @@ Seeded keys:
 4. In the desktop app, connect to host `127.0.0.1`, port `6380`, database `0`, no password, TLS disabled.
 5. Verify the desktop window opens, app version plus runtime mode are visible in the header, and the connection test succeeds.
 6. Verify the command console can run a safe read, such as `PING` or `GET smoke:string`.
-7. Verify the seeded keys appear with expected types and TTL state in the browser and inspector surfaces.
+7. Verify the seeded keys appear with expected types and TTL state in the browser and inspector surfaces, and confirm the inspector summary plus key facts stay aligned to the selected key type and current runtime.
 8. Change TTL on `smoke:string:ttl`, remove TTL from the same key, and confirm the updated TTL state is reflected in the inspector.
 9. Capture screenshots or terminal output for build, launch, connection success, key browse, TTL update, and command execution. If screenshots are unavailable, copy the in-app QA snapshot text into the smoke log.
 10. Run `./scripts/redis-fixture/stop.sh` after the session.

plans/2026-03-31-hac-26-workspace-state-foundation.md

@@ -0,0 +1,36 @@
+# HAC-26 Workspace State Foundation
+
+Date: 2026-03-31 UTC
+Owner: Senior Frontend Engineer
+Issue: HAC-26
+Scope: `apps/desktop` frontend foundation only
+
+## Context
+
+- `apps/desktop/src/App.tsx` already owns the visible desktop-v1 shell, but it still contains repeated inline logic for key filtering, selected-key fallback, live key replacement, and paged append handling.
+- These state transitions are part of the browsing and inspector foundation, not one-off UI copy, and upcoming desktop-v1 slices will need them again.
+- The PM comment on `HAC-26` asked for the highest reusable foundation return, not a new visible feature.
+
+## Decision
+
+- Do not expand product scope.
+- Extract reusable key-workspace state helpers from `App.tsx` into `src/lib`.
+- Cover the extracted state transitions with focused Vitest cases so future desktop-v1 changes can reuse the same behavior safely.
+
+## Planned Implementation
+
+1. Create a shared frontend utility for:
+   - filtering visible keys by search text
+   - resolving selected key fallback when visible results change
+   - replacing a key record after live metadata/value refresh
+   - appending paged browse results without duplicate rows
+2. Update `App.tsx` to consume the shared utility instead of inline logic.
+3. Add Vitest coverage for zero-result fallback, selection resolution, replacement merge behavior, and append deduplication.
+4. Re-run `pnpm --filter @redis-gui/desktop test` and `pnpm run desktop:build`.
+
+## Acceptance
+
+- `App.tsx` no longer owns the reusable key-workspace list and selection transitions inline.
+- The extracted helper is covered by focused tests.
+- Existing desktop frontend tests and production build remain green.
+- No backend contract or visible feature scope changes are introduced.

plans/2026-03-31-hac-29-browse-search-baseline.md

@@ -0,0 +1,47 @@
+# HAC-29 Browse And Search Baseline Stabilization
+
+Date: 2026-03-31 UTC
+Owner: Senior Frontend Engineer
+Issue: HAC-29
+Scope: `desktop-v1` browse/search hardening only
+
+## Context
+
+- `apps/desktop` already supports live browse pagination and DB-scoped search, but the visible search surface still leaves a few operator-facing gaps:
+  - no explicit feedback about whether input is treated as substring matching or raw Redis pattern matching
+  - no bounded clear action from the browser header
+  - one generic empty-state sentence was doing too much work across loading, empty DB, and filtered no-match cases
+- Current phase must stay inside browse/search hardening and must not expand into Add Key, delete execution, non-string editing, or visual refresh work.
+
+## Decision
+
+- Keep the existing workspace layout and backend contracts unchanged.
+- Extract search-state interpretation into a shared frontend helper so visible UI copy and backend browse requests use the same source of truth.
+- Improve only the key-browser and inspector feedback layer:
+  - explicit search mode label (`all keys`, `contains`, `pattern`)
+  - concise result-status message under the search input
+  - clear action for returning to normal browse state
+  - distinct empty-state copy for loading, empty DB, and no-match search results
+
+## Implemented Slice
+
+1. Added `apps/desktop/src/lib/key-browser-search.ts` plus focused tests for:
+   - blank input vs contains search vs raw wildcard-pattern classification
+   - backend request-pattern generation
+   - browser status and empty-state copy
+   - inspector empty-state copy aligned to the same search state
+2. Updated `apps/desktop/src/App.tsx` to:
+   - consume the shared search helper for live browse requests
+   - render a visible search-mode badge and status line under the browser search field
+   - expose a bounded clear action when search input is active
+   - keep browser and inspector empty-state feedback aligned
+3. Updated `docs/frontend-workspace-baseline.md` so the shared acceptance language now includes the search-mode feedback, clear action, and differentiated empty states.
+
+## Verification
+
+- `pnpm --filter @redis-gui/desktop test` -> pass (9 files / 33 tests)
+- `pnpm run desktop:build` -> pass
+
+## Remaining Risk
+
+- This environment still cannot launch a visible Tauri window, so final GUI-level browse/search smoke evidence remains a QA follow-up even though the frontend code and build path are green.

plans/2026-03-31-hac-30-inspector-readability.md

@@ -0,0 +1,46 @@
+# HAC-30 Inspector Readability
+
+Date: 2026-03-31
+Owner: Senior Frontend Engineer
+Issue: HAC-30
+
+## Goal
+
+Improve inspector readability and operator understanding without changing backend contracts or pulling next-phase scope into the current desktop-v1 slice.
+
+## Scope
+
+- clarify current inspector state for live, demo, loading, and missing-key paths
+- make value-surface semantics explicit for string and structured types
+- keep next-step operator guidance visible near the inspector surface
+- expose key facts in a stable summary card instead of relying on scattered badges and support copy
+- add focused frontend tests for the readability helper
+
+## Non-Goals
+
+- no Add Key expansion
+- no delete execution contract
+- no non-string edit support
+- no visual-theme refresh
+- no bilingual UI pass
+
+## Delivery Shape
+
+1. Add a shared inspector-readability helper that maps selected key, live record, runtime mode, and edit capability into:
+   - inspect status
+   - value-surface title and description
+   - next-step operator guidance
+   - key facts
+2. Use that helper in `apps/desktop/src/App.tsx` to:
+   - show an explicit inspector status badge
+   - add a semantic summary block above the value surface
+   - replace the previous generic support note with summary and facts cards
+3. Revalidate frontend tests and production build.
+
+## Acceptance
+
+- inspector makes live string, structured read-only, demo fallback, loading, and missing-key paths visibly distinct
+- operators can identify scope, type, TTL state, value shape, and write path without inferring them from raw payload text
+- no backend contract change is required
+- `pnpm --filter @redis-gui/desktop test` passes
+- `pnpm run desktop:build` passes