aidevops 3.26.1 → 3.28.0

package/README.md

@@ -58,7 +58,7 @@ The result: an AI operations platform that manages projects across every busines
 [![Copyright](https://img.shields.io/badge/Copyright-Marcus%20Quinn%202025--2026-blue.svg)](https://github.com/marcusquinn)
 
 <!-- Release & Version Info -->
-[![Version](https://img.shields.io/badge/Version-3.26.1-blue.svg)](https://github.com/marcusquinn/aidevops/releases)
+[![Version](https://img.shields.io/badge/Version-3.28.0-blue.svg)](https://github.com/marcusquinn/aidevops/releases)
 [![npm version](https://img.shields.io/npm/v/aidevops)](https://www.npmjs.com/package/aidevops)
 [![Homebrew](https://img.shields.io/badge/homebrew-marcusquinn%2Ftap-orange)](https://github.com/marcusquinn/homebrew-tap)
 [![GitHub repository](https://img.shields.io/badge/github-repository-181717.svg?logo=github)](https://github.com/marcusquinn/aidevops)

package/VERSION

@@ -1 +1 @@
-3.26.1
+3.28.0

package/aidevops.sh

@@ -5,7 +5,7 @@
 # AI DevOps Framework CLI
 # Usage: aidevops <command> [options]
 #
-# Version: 3.26.1
+# Version: 3.28.0
 
 set -euo pipefail
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aidevops",
-  "version": "3.26.1",
+  "version": "3.28.0",
   "description": "AI DevOps Framework - AI-assisted development workflows, code quality, and deployment automation",
   "type": "module",
   "workspaces": [

package/packages/gui-web/src/App.tsx

@@ -212,6 +212,8 @@ export function App(): ReactElement {
         goForward={goForward}
         selectedLocalRepoIndex={selectedLocalRepoIndex}
         setActiveSurface={setActiveSurface}
+        setConversationMode={setConversationMode}
+        setShellMode={setShellMode}
         shellMode={shellMode}
         status={status.data}
       />

package/packages/gui-web/src/AppNavigation.tsx

@@ -20,6 +20,7 @@ import {
   FiGrid,
   FiHash,
   FiHardDrive,
+  FiHelpCircle,
   FiLink,
   FiLink2,
   FiList,
@@ -54,6 +55,8 @@ const surfaceIcons: Record<SurfaceIconName, IconType> = {
   globe: FiGlobe,
   grid: FiGrid,
   hardDrive: FiHardDrive,
+  hash: FiHash,
+  help: FiHelpCircle,
   link: FiLink,
   list: FiList,
   lock: FiLock,

package/packages/gui-web/src/AppWorkspace.tsx

@@ -1,10 +1,11 @@
 /* jshint esversion: 11 */
-import { type ReactElement, type ReactNode, useEffect, useMemo, useRef, useState } from "react";
-import { FiBell, FiChevronLeft, FiChevronRight, FiCommand, FiCpu, FiGlobe, FiHash, FiLogOut, FiMessageSquare, FiSearch, FiSettings, FiShield, FiUser } from "react-icons/fi";
+import { type ReactElement, type ReactNode, useEffect, useState } from "react";
+import { FiBell, FiChevronLeft, FiChevronRight, FiCommand, FiGlobe, FiHash, FiHelpCircle, FiLogOut, FiMessageSquare, FiSearch, FiSettings, FiShield, FiTerminal, FiUser } from "react-icons/fi";
 import type { GuiFileRootId, GuiStatusData } from "../../gui-shared/src";
 import { SurfaceGlyph } from "./AppNavigation";
 import type { ConversationMode, ShellMode, SurfaceId, SurfaceNavItem } from "./app-model";
-import { inventorySurfaceConfigs, orderedNavItems, text } from "./app-model";
+import { inventorySurfaceConfigs, text } from "./app-model";
+import { CommandPalette, commandPaletteShortcutQuery } from "./CommandPalette";
 import { FileExplorerSurface } from "./FileExplorerSurface";
 import { AppsSurface, EditableInventorySurface, InstallationSurface } from "./InventorySurfaces";
 import { AiProvidersSurface, LocalReposSurface, LockedVaultGate, OverviewSurface, PlannedSurface, ProjectsSurface, SecuritySurface, VaultSurface } from "./StatusSurfaces";
@@ -15,7 +16,7 @@ const communityLinks = {
   x: "https://x.com/marcuswquinn",
 } as const;
 
-export function Workspace({ activeItem, activeSectionLabel, activeSurface, canGoBack, canGoForward, conversationMode, fileRoot, goBack, goForward, selectedLocalRepoIndex, setActiveSurface, shellMode, status }: {
+export function Workspace({ activeItem, activeSectionLabel, activeSurface, canGoBack, canGoForward, conversationMode, fileRoot, goBack, goForward, selectedLocalRepoIndex, setActiveSurface, setConversationMode, setShellMode, shellMode, status }: {
   activeItem: SurfaceNavItem;
   activeSectionLabel: string;
   activeSurface: SurfaceId;
@@ -27,12 +28,14 @@ export function Workspace({ activeItem, activeSectionLabel, activeSurface, canGo
   goForward: () => void;
   selectedLocalRepoIndex: number;
   setActiveSurface: (surface: SurfaceId) => void;
+  setConversationMode: (mode: ConversationMode) => void;
+  setShellMode: (mode: ShellMode) => void;
   shellMode: ShellMode;
   status: GuiStatusData;
 }) {
   return (
     <section className="app-inset" aria-label={text.workspaceLabel}>
-      <WorkspaceHeader activeItem={activeItem} activeSectionLabel={activeSectionLabel} activeSurface={activeSurface} canGoBack={canGoBack} canGoForward={canGoForward} goBack={goBack} goForward={goForward} setActiveSurface={setActiveSurface} status={status} />
+      <WorkspaceHeader activeItem={activeItem} activeSectionLabel={activeSectionLabel} activeSurface={activeSurface} canGoBack={canGoBack} canGoForward={canGoForward} goBack={goBack} goForward={goForward} setActiveSurface={setActiveSurface} setConversationMode={setConversationMode} setShellMode={setShellMode} status={status} />
       <div className="workspace-scroll">
         {shellMode === "sessions"
           ? <ConversationWorkspace conversationMode={conversationMode} selectedLocalRepoIndex={selectedLocalRepoIndex} status={status} />
@@ -42,7 +45,7 @@ export function Workspace({ activeItem, activeSectionLabel, activeSurface, canGo
   );
 }
 
-function WorkspaceHeader({ activeItem, activeSectionLabel, activeSurface, canGoBack, canGoForward, goBack, goForward, setActiveSurface, status }: {
+function WorkspaceHeader({ activeItem, activeSectionLabel, activeSurface, canGoBack, canGoForward, goBack, goForward, setActiveSurface, setConversationMode, setShellMode, status }: {
   activeItem: SurfaceNavItem;
   activeSectionLabel: string;
   activeSurface: SurfaceId;
@@ -51,6 +54,8 @@ function WorkspaceHeader({ activeItem, activeSectionLabel, activeSurface, canGoB
   goBack: () => void;
   goForward: () => void;
   setActiveSurface: (surface: SurfaceId) => void;
+  setConversationMode: (mode: ConversationMode) => void;
+  setShellMode: (mode: ShellMode) => void;
   status: GuiStatusData;
 }): ReactElement {
   const [assistantOpen, setAssistantOpen] = useState(false);
@@ -63,30 +68,30 @@ function WorkspaceHeader({ activeItem, activeSectionLabel, activeSurface, canGoB
 
   useEffect(() => {
     const openCommandPalette = (event: KeyboardEvent) => {
-      if ((event.metaKey || event.ctrlKey) && event.key.toLowerCase() === "k") {
-        event.preventDefault();
-        setCommandInitialQuery("");
-        setCommandOpen(true);
-        return;
-      }
-
-      if (event.key === "/" && !isEditableShortcutTarget(event.target)) {
-        event.preventDefault();
-        setCommandInitialQuery("/");
-        setCommandOpen(true);
-      }
+      handleWorkspaceShortcut(event, {
+        goBack,
+        goForward,
+        openCommand: (query) => {
+          setCommandInitialQuery(query);
+          setCommandOpen(true);
+        },
+      });
     };
 
     window.addEventListener("keydown", openCommandPalette);
     return () => window.removeEventListener("keydown", openCommandPalette);
-  }, []);
+  }, [goBack, goForward]);
 
   const closeMenus = () => {
     setNotificationsOpen(false);
     setProfileOpen(false);
   };
 
-  const openSurface = (surface: SurfaceId) => {
+  const openItem = ({ conversationMode, shellMode, surface }: { conversationMode?: ConversationMode; shellMode?: ShellMode; surface: SurfaceId }) => {
+    setShellMode(shellMode ?? "devices");
+    if (conversationMode) {
+      setConversationMode(conversationMode);
+    }
     setActiveSurface(surface);
     closeMenus();
     setCommandOpen(false);
@@ -114,28 +119,45 @@ function WorkspaceHeader({ activeItem, activeSectionLabel, activeSurface, canGoB
       </div>
       <div className="header-actions">
         <div className="header-action-menu">
+          <button aria-label="Open help" className="header-icon-button" onClick={() => openItem({ surface: "help" })} title="Help (?)" type="button">
+            <FiHelpCircle aria-hidden="true" />
+          </button>
           <button aria-expanded={notificationsOpen} aria-label="Open notifications" className="header-icon-button" onClick={() => { setNotificationsOpen((current) => !current); setProfileOpen(false); }} type="button">
             <FiBell aria-hidden="true" />
             <span className="notification-dot" aria-hidden="true" />
           </button>
-          {notificationsOpen ? <NotificationsMenu openSurface={openSurface} /> : null}
+          {notificationsOpen ? <NotificationsMenu openSurface={(surface) => openItem({ surface })} /> : null}
         </div>
-        <button aria-pressed={assistantOpen} aria-label="Toggle AI Assistant" className={assistantOpen ? "header-icon-button active" : "header-icon-button"} onClick={() => setAssistantOpen((current) => !current)} type="button">
-          <FiCpu aria-hidden="true" />
+        <button aria-pressed={assistantOpen} aria-label="Toggle AI Assistant" className={assistantOpen ? "header-icon-button active" : "header-icon-button"} onClick={() => setAssistantOpen((current) => !current)} title="AI sessions (_)" type="button">
+          <FiTerminal aria-hidden="true" />
         </button>
         <div className="header-action-menu">
           <button aria-expanded={profileOpen} aria-label={`Open profile menu for ${userName}`} className="profile-avatar-button" onClick={() => { setProfileOpen((current) => !current); setNotificationsOpen(false); }} title={userName} type="button">
             <span>{userInitials}</span>
           </button>
-          {profileOpen ? <ProfileMenu openSurface={openSurface} userName={userName} /> : null}
+          {profileOpen ? <ProfileMenu openSurface={(surface) => openItem({ surface })} userName={userName} /> : null}
         </div>
       </div>
       {assistantOpen ? <AssistantPanel activeSurface={activeSurface} userName={userName} /> : null}
-      {commandOpen ? <CommandPalette close={() => setCommandOpen(false)} initialQuery={commandInitialQuery} openSurface={openSurface} status={status} /> : null}
+      {commandOpen ? <CommandPalette activeSurface={activeSurface} close={() => setCommandOpen(false)} initialQuery={commandInitialQuery} openItem={openItem} status={status} /> : null}
     </header>
   );
 }
 
+function handleWorkspaceShortcut(event: KeyboardEvent, actions: { goBack: () => void; goForward: () => void; openCommand: (query: string) => void }): void {
+  const shortcutQuery = commandPaletteShortcutQuery(event);
+  const isEditableTarget = isEditableShortcutTarget(event.target);
+  const commandQuery = (event.metaKey || event.ctrlKey) && event.key.toLowerCase() === "k" ? "" : shortcutQuery;
+
+  if (commandQuery !== undefined && !isEditableTarget) {
+    event.preventDefault();
+    actions.openCommand(commandQuery);
+  } else if (event.key === "Backspace" && !isEditableTarget) {
+    event.preventDefault();
+    (event.shiftKey ? actions.goForward : actions.goBack)();
+  }
+}
+
 function isEditableShortcutTarget(target: EventTarget | null): boolean {
   if (!(target instanceof HTMLElement)) {
     return false;
@@ -235,114 +257,6 @@ function AssistantPanel({ activeSurface, userName }: { activeSurface: SurfaceId;
   );
 }
 
-interface CommandPaletteItem {
-  description: string;
-  icon: SurfaceNavItem["icon"];
-  id: string;
-  label: string;
-  searchText: string;
-  surface: SurfaceId;
-  tag: string;
-}
-
-const slashCommandItems: CommandPaletteItem[] = [
-  { id: "slash-add-device", label: "/add-device", description: "Start device pairing setup", icon: "device", searchText: "/add-device add device pair machine", surface: "devices", tag: "Command" },
-  { id: "slash-add-local-repo", label: "/add-local-repo", description: "Add a local repository path", icon: "folder", searchText: "/add-local-repo add local repo git", surface: "git", tag: "Command" },
-  { id: "slash-add-remote-repo", label: "/add-remote-repo", description: "Register a remote repository", icon: "git", searchText: "/add-remote-repo add remote repo", surface: "projects", tag: "Command" },
-  { id: "slash-add-secret", label: "/add-secret", description: "Add a protected secret reference", icon: "shield", searchText: "/add-secret add secret vault", surface: "security", tag: "Command" },
-  { id: "slash-add-ai-provider", label: "/add-ai-provider", description: "Connect an AI provider account", icon: "users", searchText: "/add-ai-provider add ai provider oauth", surface: "aiProviders", tag: "Command" },
-];
-
-const plannedChannelItems: CommandPaletteItem[] = [
-  { id: "channel-devops", label: "#devops", description: "Chat channel for aidevops operations", icon: "message", searchText: "#devops devops channel chat", surface: "messagingAccounts", tag: "Channel" },
-  { id: "channel-comms", label: "#comms", description: "Chat channel for communications", icon: "message", searchText: "#comms comms channel chat", surface: "messagingAccounts", tag: "Channel" },
-];
-
-function CommandPalette({ close, initialQuery, openSurface, status }: { close: () => void; initialQuery: string; openSurface: (surface: SurfaceId) => void; status: GuiStatusData }): ReactElement {
-  const [query, setQuery] = useState(initialQuery);
-  const inputRef = useRef<HTMLInputElement>(null);
-  const matches = useMemo(() => {
-    const normalizedQuery = query.trim().toLowerCase();
-    const surfaceItems: CommandPaletteItem[] = orderedNavItems.map((item) => ({
-      description: item.description,
-      icon: item.icon,
-      id: `surface-${item.id}`,
-      label: item.label,
-      searchText: `${item.label} ${item.description}`,
-      surface: item.id,
-      tag: "Surface",
-    }));
-    const sessionItems: CommandPaletteItem[] = status.opencode_sessions.sessions.map((session) => ({
-      description: `AI session in ${session.repo_path_ref}`,
-      icon: "terminal",
-      id: `session-${session.id_ref}`,
-      label: `#${session.title}`,
-      searchText: `#${session.title} ${session.title} ${session.repo_path_ref} ${session.agent} ${session.model}`,
-      surface: "git",
-      tag: "AI session",
-    }));
-    const directMessageItems: CommandPaletteItem[] = [{
-      description: "Direct message thread placeholder",
-      icon: "users",
-      id: "dm-local-user",
-      label: `@${status.machine.username || "local-user"}`,
-      searchText: `@${status.machine.username || "local-user"} direct message dm person local user`,
-      surface: "messagingAccounts",
-      tag: "Direct message",
-    }];
-    const items = [...surfaceItems, ...sessionItems, ...plannedChannelItems, ...directMessageItems, ...slashCommandItems];
-    const prefix = normalizedQuery.charAt(0);
-    const scopedItems = prefix === "/"
-      ? slashCommandItems
-      : prefix === "@"
-        ? directMessageItems
-        : prefix === "#"
-          ? [...sessionItems, ...plannedChannelItems]
-          : items;
-
-    return scopedItems
-      .filter((item) => normalizedQuery.length === 0 || item.searchText.toLowerCase().includes(normalizedQuery))
-      .slice(0, 8);
-  }, [query, status.machine.username, status.opencode_sessions.sessions]);
-
-  useEffect(() => {
-    inputRef.current?.focus();
-  }, []);
-
-  useEffect(() => {
-    const closeOnEscape = (event: KeyboardEvent) => {
-      if (event.key === "Escape") {
-        close();
-      }
-    };
-
-    window.addEventListener("keydown", closeOnEscape);
-    return () => window.removeEventListener("keydown", closeOnEscape);
-  }, [close]);
-
-  return (
-    <div className="command-palette-backdrop" role="presentation">
-      <button aria-label="Close command palette" className="command-palette-scrim" onClick={close} type="button" />
-      <section aria-label="Command palette" className="command-palette">
-        <label className="command-input-row">
-          <FiSearch aria-hidden="true" />
-          <input ref={inputRef} onChange={(event) => setQuery(event.currentTarget.value)} placeholder="Search commands, #sessions, #channels, @people, or /actions" value={query} />
-        </label>
-        <ul>
-          {matches.map((item) => (
-            <li key={item.id}>
-              <button onClick={() => openSurface(item.surface)} type="button">
-                <span className="surface-icon" aria-hidden="true"><SurfaceGlyph icon={item.icon} /></span>
-                <span><strong>{item.label}</strong><small>{item.tag} · {item.description}</small></span>
-              </button>
-            </li>
-          ))}
-        </ul>
-      </section>
-    </div>
-  );
-}
-
 function SurfaceContent({ activeItem, activeSurface, fileRoot, status }: {
   activeItem: SurfaceNavItem;
   activeSurface: SurfaceId;
@@ -353,6 +267,7 @@ function SurfaceContent({ activeItem, activeSurface, fileRoot, status }: {
   const vaultCollection = vaultCollectionForSurface(status.vault, activeSurface);
   const staticSurfaces: Partial<Record<SurfaceId, ReactNode>> = {
     overview: <OverviewSurface status={status} />,
+    help: <HelpSurface />,
     settings: <SettingsSurface status={status} />,
     notifications: <NotificationsSurface />,
     admin: <AdminSurface />,
@@ -406,6 +321,40 @@ function SurfaceContent({ activeItem, activeSurface, fileRoot, status }: {
   return staticSurfaces[activeSurface] ?? null;
 }
 
+function HelpSurface(): ReactElement {
+  const shortcuts = [
+    ["#", "Channels"],
+    ["_", "AI sessions"],
+    ["&", "Infrastructure"],
+    ["?", "Help"],
+    [">", "New terminal command"],
+    ["+", "Add commands"],
+    ["-", "Remove commands"],
+    ["/", "Slash commands"],
+    ["=", "Comms"],
+    ["~", "Settings and config"],
+    ["!", "Notifications"],
+    [".", "Agents"],
+    ["*", "Secrets and passwords"],
+    [":", "Emoji picker"],
+    ["^", "Copy current page link"],
+  ];
+
+  return (
+    <section className="settings-surface help-surface">
+      <div className="planned-card">
+        <h2>Help</h2>
+        <p>Use the command palette shortcuts from anywhere outside text inputs. Recent selections appear first until you keep typing to filter.</p>
+      </div>
+      <ul className="shortcut-list">
+        {shortcuts.map(([shortcut, label]) => <li key={shortcut}><kbd>{shortcut}</kbd><span>{label}</span></li>)}
+        <li><kbd>Backspace</kbd><span>Previous page</span></li>
+        <li><kbd>Shift Backspace</kbd><span>Next page</span></li>
+      </ul>
+    </section>
+  );
+}
+
 function SettingsSurface({ status }: { status: GuiStatusData }): ReactElement {
   return (
     <section className="settings-surface">

package/packages/gui-web/src/CommandPalette.tsx

@@ -0,0 +1,286 @@
+/* jshint esversion: 11 */
+import { type ReactElement, useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { createPortal } from "react-dom";
+import { FiSearch } from "react-icons/fi";
+import { SurfaceGlyph } from "./AppNavigation";
+import type { ConversationMode, ShellMode, SurfaceId, SurfaceIconName, SurfaceNavItem } from "./app-model";
+import { navGroups, orderedNavItems, utilityNavItems } from "./app-model";
+import type { GuiStatusData } from "../../gui-shared/src";
+
+interface CommandPaletteItem {
+  action?: "copy-current-link";
+  description: string;
+  conversationMode?: ConversationMode;
+  icon: SurfaceIconName;
+  iconGlyph?: string;
+  id: string;
+  label: string;
+  searchText: string;
+  shellMode?: ShellMode;
+  surface: SurfaceId;
+  tag: string;
+}
+
+const commandPaletteRecentStorageKey = "aidevops-gui-command-palette-recents";
+const commandPaletteRecentLimit = 5;
+
+const slashCommandItems: CommandPaletteItem[] = [
+  { id: "slash-add-device", label: "/add-device", description: "Start device pairing setup", icon: "device", searchText: "/add-device add device pair machine", surface: "devices", tag: "Command" },
+  { id: "slash-add-local-repo", label: "/add-local-repo", description: "Add a local repository path", icon: "folder", searchText: "/add-local-repo add local repo git", surface: "git", tag: "Command" },
+  { id: "slash-add-remote-repo", label: "/add-remote-repo", description: "Register a remote repository", icon: "git", searchText: "/add-remote-repo add remote repo", surface: "projects", tag: "Command" },
+  { id: "slash-add-secret", label: "/add-secret", description: "Add a protected secret reference", icon: "shield", searchText: "/add-secret add secret vault", surface: "security", tag: "Command" },
+  { id: "slash-add-ai-provider", label: "/add-ai-provider", description: "Connect an AI provider account", icon: "users", searchText: "/add-ai-provider add ai provider oauth", surface: "aiProviders", tag: "Command" },
+];
+
+const addCommandItems: CommandPaletteItem[] = slashCommandItems.map((item) => {
+  const label = item.label.replace("/", "+");
+
+  return { ...item, id: item.id.replace("slash-", "plus-"), label, searchText: `${label} ${item.searchText}`, tag: "Add" };
+});
+
+const removeCommandItems: CommandPaletteItem[] = [
+  { id: "remove-device", label: "-device", description: "Remove a paired device placeholder", icon: "device", searchText: "-device remove device unpair machine", surface: "devices", tag: "Remove" },
+  { id: "remove-local-repo", label: "-local-repo", description: "Remove a local repository reference placeholder", icon: "folder", searchText: "-local-repo remove local repo git", surface: "git", tag: "Remove" },
+  { id: "remove-secret", label: "-secret", description: "Remove a protected secret reference placeholder", icon: "shield", searchText: "-secret remove secret vault password", surface: "security", tag: "Remove" },
+];
+
+const terminalCommandItems: CommandPaletteItem[] = [
+  { id: "terminal-new-command", label: "> new terminal command", description: "Send a command to a new terminal session", icon: "terminal", searchText: "> terminal command new session shell", surface: "localSetup", tag: "Terminal" },
+];
+
+const emojiItems: CommandPaletteItem[] = [
+  { id: "emoji-thumbs-up", label: ":thumbsup:", description: "Copy or insert 👍", icon: "message", iconGlyph: "👍", searchText: ":thumbsup thumbs up approve emoji", surface: "messagingAccounts", tag: "Emoji" },
+  { id: "emoji-check", label: ":white_check_mark:", description: "Copy or insert ✅", icon: "message", iconGlyph: "✅", searchText: ":white_check_mark check done emoji", surface: "messagingAccounts", tag: "Emoji" },
+  { id: "emoji-eyes", label: ":eyes:", description: "Copy or insert 👀", icon: "message", iconGlyph: "👀", searchText: ":eyes review look emoji", surface: "messagingAccounts", tag: "Emoji" },
+];
+
+const plannedChannelItems: CommandPaletteItem[] = [
+  { id: "channel-devops", label: "#devops", description: "Chat channel for aidevops operations", icon: "hash", searchText: "#devops devops channel chat", surface: "messagingAccounts", shellMode: "sessions", conversationMode: "people", tag: "Channel" },
+  { id: "channel-comms", label: "#comms", description: "Chat channel for communications", icon: "hash", searchText: "#comms comms channel chat", surface: "messagingAccounts", shellMode: "sessions", conversationMode: "people", tag: "Channel" },
+];
+
+export interface CommandPaletteSelection {
+  conversationMode?: ConversationMode;
+  shellMode?: ShellMode;
+  surface: SurfaceId;
+}
+
+export function CommandPalette({ activeSurface, close, initialQuery, openItem, status }: { activeSurface: SurfaceId; close: () => void; initialQuery: string; openItem: (selection: CommandPaletteSelection) => void; status: GuiStatusData }): ReactElement {
+  const allItems = useMemo(() => commandPaletteItems(status, activeSurface), [activeSurface, status]);
+  const [query, setQuery] = useState(initialQuery);
+  const [activeIndex, setActiveIndex] = useState(0);
+  const [recentIds, setRecentIds] = useState<string[]>(() => readCommandPaletteRecentIds());
+  const inputRef = useRef<HTMLInputElement>(null);
+  const matches = useMemo(() => commandPaletteMatches(allItems, query, recentIds), [allItems, query, recentIds]);
+
+  const selectItem = useCallback((item: CommandPaletteItem | undefined) => {
+    if (item) {
+      const nextRecentIds = rememberCommandPaletteItemId(item.id, recentIds);
+      setRecentIds(nextRecentIds);
+      if (item.action === "copy-current-link") {
+        void copyCurrentSurfaceLink(item.surface);
+      }
+      openItem({ conversationMode: item.conversationMode, shellMode: item.shellMode, surface: item.surface });
+    }
+  }, [openItem, recentIds]);
+
+  useEffect(() => {
+    inputRef.current?.focus();
+  }, []);
+
+  useEffect(() => {
+    setActiveIndex((current) => Math.min(current, Math.max(0, matches.length - 1)));
+  }, [matches.length]);
+
+  useEffect(() => {
+    const handlePaletteKeys = (event: KeyboardEvent) => {
+      if (event.key === "Escape") {
+        close();
+      } else if (event.key === "ArrowDown") {
+        event.preventDefault();
+        setActiveIndex((current) => Math.min(matches.length - 1, current + 1));
+      } else if (event.key === "ArrowUp") {
+        event.preventDefault();
+        setActiveIndex((current) => Math.max(0, current - 1));
+      } else if (event.key === "Enter") {
+        event.preventDefault();
+        selectItem(matches[activeIndex]);
+      }
+    };
+
+    window.addEventListener("keydown", handlePaletteKeys);
+    return () => window.removeEventListener("keydown", handlePaletteKeys);
+  }, [activeIndex, close, matches, selectItem]);
+
+  return createPortal(
+    <div className="command-palette-backdrop" role="presentation">
+      <button aria-label="Close command palette" className="command-palette-scrim" onClick={close} type="button" />
+      <section aria-label="Command palette" className="command-palette">
+        <label className="command-input-row">
+          <FiSearch aria-hidden="true" />
+          <input aria-activedescendant={matches[activeIndex]?.id} aria-controls="command-palette-results" aria-expanded="true" aria-autocomplete="list" ref={inputRef} onChange={(event) => { setQuery(event.currentTarget.value); setActiveIndex(0); }} placeholder="Search /commands, #channels, _sessions, &infra, ?help, .agents" role="combobox" value={query} />
+        </label>
+        <ul id="command-palette-results">
+          {matches.map((item, index) => (
+            <li key={item.id}>
+              <button className={index === activeIndex ? "active" : undefined} id={item.id} onClick={() => selectItem(item)} type="button">
+                <span className="surface-icon" aria-hidden="true">{item.iconGlyph ?? <SurfaceGlyph icon={item.icon} />}</span>
+                <span><strong>{item.label}</strong><small>{item.tag} · {item.description}</small></span>
+              </button>
+            </li>
+          ))}
+        </ul>
+      </section>
+    </div>,
+    document.body,
+  );
+}
+
+export function commandPaletteShortcutQuery(event: Pick<KeyboardEvent, "key" | "metaKey" | "ctrlKey" | "altKey">): string | undefined {
+  if (event.metaKey || event.ctrlKey || event.altKey) {
+    return undefined;
+  }
+
+  return new Map(commandPaletteShortcutEntries).get(event.key);
+}
+
+export const commandPaletteShortcutEntries = ["#", "_", "&", "?", ">", "+", "-", "/", "=", "~", "!", ".", "*", ":", "^"].map((shortcut) => [shortcut, shortcut] as const);
+
+export function orderCommandItemsByRecency<T extends { id: string }>(items: T[], recentIds: string[]): T[] {
+  const recentItems = recentIds
+    .map((id) => items.find((item) => item.id === id))
+    .filter((item): item is T => item !== undefined);
+  const recentItemIds = new Set(recentItems.map((item) => item.id));
+
+  return [...recentItems, ...items.filter((item) => !recentItemIds.has(item.id))];
+}
+
+export function rememberCommandPaletteItemId(itemId: string, currentIds: string[]): string[] {
+  const nextIds = [itemId, ...currentIds.filter((id) => id !== itemId)].slice(0, commandPaletteRecentLimit);
+  writeCommandPaletteRecentIds(nextIds);
+  return nextIds;
+}
+
+export function commandPaletteMatches(items: CommandPaletteItem[], query: string, recentIds: string[]): CommandPaletteItem[] {
+  const normalizedQuery = query.trim().toLowerCase();
+  const prefix = normalizedQuery.charAt(0);
+  const scopedItems = itemsForCommandPrefix(items, prefix);
+
+  if (normalizedQuery.length === 0 || commandPaletteShortcutEntries.some(([shortcut]) => shortcut === normalizedQuery)) {
+    return orderCommandItemsByRecency(scopedItems, recentIds).slice(0, 8);
+  }
+
+  return scopedItems
+    .filter((item) => item.searchText.toLowerCase().includes(normalizedQuery))
+    .slice(0, 8);
+}
+
+function commandPaletteItems(status: GuiStatusData, activeSurface: SurfaceId): CommandPaletteItem[] {
+  const surfaceItems: CommandPaletteItem[] = orderedNavItems.map((item) => ({
+    description: item.description,
+    icon: item.icon,
+    id: `surface-${item.id}`,
+    label: item.label,
+    searchText: `${item.label} ${item.description}`,
+    surface: item.id,
+    tag: surfaceTagForItem(item),
+  }));
+  const helpItems: CommandPaletteItem[] = [
+    { id: "help-shortcuts", label: "? shortcuts", description: "Open command palette and keyboard shortcut help", icon: "help", searchText: "? shortcuts help command palette keyboard", surface: "help", tag: "Help" },
+  ];
+  const currentLinkItems: CommandPaletteItem[] = [
+    { action: "copy-current-link", id: "copy-current-link", label: `^ copy ${activeSurface} link`, description: "Copy a link that can reopen this page in the web or local app", icon: "link", searchText: `^ link copy current page url ${activeSurface} aidevops://surface/${activeSurface}`, surface: activeSurface, tag: "Link" },
+  ];
+  const sessionItems: CommandPaletteItem[] = status.opencode_sessions.sessions.map((session) => ({
+    description: `AI session in ${session.repo_path_ref}`,
+    icon: "terminal",
+    iconGlyph: "_",
+    id: `session-${session.id_ref}`,
+    label: `_${session.title}`,
+    searchText: `_${session.title} ${session.title} ${session.repo_path_ref} ${session.agent} ${session.model}`,
+    surface: "git",
+    shellMode: "sessions",
+    conversationMode: "ai",
+    tag: "AI session",
+  }));
+  const directMessageItems: CommandPaletteItem[] = [{
+    description: "Direct message thread placeholder",
+    icon: "users",
+    id: "dm-local-user",
+    label: `@${status.machine.username || "local-user"}`,
+    searchText: `@${status.machine.username || "local-user"} direct message dm person local user`,
+    surface: "messagingAccounts",
+    tag: "Direct message",
+  }];
+
+  return [...surfaceItems, ...helpItems, ...sessionItems, ...plannedChannelItems, ...directMessageItems, ...slashCommandItems, ...addCommandItems, ...removeCommandItems, ...terminalCommandItems, ...emojiItems, ...currentLinkItems];
+}
+
+function itemsForCommandPrefix(items: CommandPaletteItem[], prefix: string): CommandPaletteItem[] {
+  const tagsByPrefix = new Map<string, string[]>([
+    ["/", ["Command"]],
+    ["@", ["Direct message"]],
+    ["#", ["Channel"]],
+    ["_", ["AI session"]],
+    ["&", ["Infrastructure"]],
+    ["?", ["Help"]],
+    [">", ["Terminal"]],
+    ["+", ["Add"]],
+    ["-", ["Remove"]],
+    ["=", ["Comms"]],
+    ["~", ["Settings"]],
+    ["!", ["Notifications"]],
+    [".", ["Agent"]],
+    ["*", ["Secret"]],
+    [":", ["Emoji"]],
+    ["^", ["Link"]],
+  ]);
+  const allowedTags = tagsByPrefix.get(prefix) ?? ["Surface"];
+
+  return items.filter((item) => allowedTags.includes(item.tag));
+}
+
+function surfaceTagForItem(item: SurfaceNavItem): string {
+  const explicitTags: Partial<Record<SurfaceId, string>> = {
+    agents: "Agent",
+    config: "Settings",
+    help: "Help",
+    notifications: "Notifications",
+    projectConfig: "Settings",
+    security: "Secret",
+    settings: "Settings",
+    vault: "Secret",
+  };
+  const infrastructureIds = navGroups.find((group) => group.label === "Infrastructure")?.items.map((groupItem) => groupItem.id) ?? [];
+  const commsIds = navGroups.filter((group) => group.mode === "comms").flatMap((group) => group.items.map((groupItem) => groupItem.id));
+  const utilityFallback = utilityNavItems.some((utilityItem) => utilityItem.id === item.id) ? "Surface" : undefined;
+
+  return explicitTags[item.id] ?? (infrastructureIds.includes(item.id) ? "Infrastructure" : undefined) ?? (commsIds.includes(item.id) ? "Comms" : undefined) ?? utilityFallback ?? "Surface";
+}
+
+async function copyCurrentSurfaceLink(surface: SurfaceId): Promise<void> {
+  const browserUrl = typeof window === "undefined" ? "" : window.location.href.split("#")[0];
+  const link = browserUrl.length > 0 ? `${browserUrl}#surface=${surface}` : `aidevops://surface/${surface}`;
+
+  if (typeof navigator !== "undefined" && navigator.clipboard) {
+    await navigator.clipboard.writeText(link);
+  }
+}
+
+function readCommandPaletteRecentIds(): string[] {
+  try {
+    const storedValue = window.localStorage.getItem(commandPaletteRecentStorageKey);
+    const parsedValue: unknown = storedValue ? JSON.parse(storedValue) : [];
+    return Array.isArray(parsedValue) ? parsedValue.filter((value): value is string => typeof value === "string").slice(0, commandPaletteRecentLimit) : [];
+  } catch {
+    return [];
+  }
+}
+
+function writeCommandPaletteRecentIds(ids: string[]): void {
+  try {
+    window.localStorage.setItem(commandPaletteRecentStorageKey, JSON.stringify(ids.slice(0, commandPaletteRecentLimit)));
+  } catch {
+    // Ignore unavailable storage; command navigation still works without recents.
+  }
+}

package/packages/gui-web/src/app-model.ts

@@ -32,6 +32,8 @@ export const surfaceIconNames = {
   globe: true,
   grid: true,
   hardDrive: true,
+  hash: true,
+  help: true,
   link: true,
   list: true,
   lock: true,
@@ -48,6 +50,7 @@ export const surfaceIconNames = {
 export type SurfaceIconName = keyof typeof surfaceIconNames;
 export const surfaceIds = [
   "overview",
+  "help",
   "settings",
   "notifications",
   "admin",
@@ -147,6 +150,8 @@ export const text = {
   configIntro: "Read-only file explorer for ~/.config/aidevops. Contents stay hidden until redaction rules land.",
   copyPath: "Copy path",
   dashboard: "Dashboard",
+  help: "Help",
+  helpIntro: "Command shortcuts, navigation hints, and aidevops workflow guidance will collect here.",
   domains: "Domains",
   domainsIntro: "Draft domain ownership inventory across providers.",
   draftOnly: "Local browser draft only. Saving requires a write-action manifest, confirmation, and audit trail.",
@@ -396,6 +401,7 @@ export const dashboardNavItem: SurfaceNavItem = {
 };
 
 export const utilityNavItems: SurfaceNavItem[] = [
+  { id: "help", label: text.help, description: "Shortcuts, command palette symbols, and support", icon: "help", badge: text.planned },
   { id: "settings", label: "Settings", description: "Profile, login, notifications, language, and theme preferences", icon: "settings", badge: text.planned },
   { id: "notifications", label: "Notifications", description: "Notification inbox and delivery preferences", icon: "message", badge: text.planned },
   { id: "admin", label: "Admin", description: "Hosted administration controls", icon: "shield", badge: text.planned },

package/packages/gui-web/src/dashboard.ts

@@ -38,7 +38,7 @@ export function renderDashboardHtml(status: GuiResponseEnvelope<GuiStatusData>):
     .join("");
   const navSections = [
     { heading: "Development", items: ["Local Repos", "Remote Repos", "Secrets", "AI Providers"] },
-    { heading: "Account", items: ["Settings", "Notifications", "Admin"] },
+    { heading: "Account", items: ["Help", "Settings", "Notifications", "Admin"] },
     { heading: "Operations", items: ["Dashboard", "Vault", "Agents file explorer", "Config", "Local Setup", "Routines"] },
     { heading: "Infrastructure", items: ["Devices", "VPNs & Proxies", "Apps", "Installation", "Registrars", "Hosts", "Servers"] },
     { heading: "Identities", items: ["Brands", "Domains", "Personas"] },

package/packages/gui-web/src/styles.css

@@ -1066,12 +1066,14 @@ code {
 
 .command-palette-backdrop {
   align-items: center;
-  background: rgb(0 0 0 / 28%);
+  backdrop-filter: blur(8px) saturate(120%);
+  background: rgb(0 0 0 / 34%);
   display: flex;
   inset: 0;
   justify-content: center;
   position: fixed;
   z-index: 20;
+  -webkit-backdrop-filter: blur(8px) saturate(120%);
 }
 
 .command-palette-scrim {
@@ -1092,7 +1094,6 @@ code {
   max-width: min(680px, calc(100vw - 32px));
   padding: 14px;
   position: relative;
-  transform: translateY(-2vh);
   width: 100%;
 }
 
@@ -1137,7 +1138,8 @@ code {
 }
 
 .command-palette button:hover,
-.command-palette button:focus-visible {
+.command-palette button:focus-visible,
+.command-palette button.active {
   background: var(--surface-muted);
   color: var(--accent);
   outline: none;
@@ -1350,6 +1352,38 @@ code {
   padding: 14px;
 }
 
+.shortcut-list {
+  display: grid;
+  gap: 8px;
+  grid-template-columns: repeat(auto-fit, minmax(220px, 1fr));
+  list-style: none;
+  margin: 0;
+  padding: 0;
+}
+
+.shortcut-list li {
+  align-items: center;
+  background: var(--surface-elevated);
+  border: 1px solid var(--border);
+  border-radius: 16px;
+  display: flex;
+  gap: 12px;
+  padding: 12px 14px;
+}
+
+.shortcut-list kbd {
+  align-items: center;
+  background: var(--surface-muted);
+  border: 1px solid var(--border);
+  border-radius: 10px;
+  color: var(--accent);
+  display: inline-flex;
+  font-weight: 900;
+  justify-content: center;
+  min-width: 34px;
+  padding: 4px 8px;
+}
+
 .notification-list span {
   color: var(--text-muted);
 }

package/setup.sh

@@ -12,7 +12,7 @@ shopt -s inherit_errexit 2>/dev/null || true
 # AI Assistant Server Access Framework Setup Script
 # Helps developers set up the framework for their infrastructure
 #
-# Version: 3.26.1
+# Version: 3.28.0
 #
 # Quick Install:
 #   npm install -g aidevops && aidevops update          (recommended)