aidevops 3.27.0 → 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.27.0-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.27.0
+3.28.0

package/aidevops.sh

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aidevops",
-  "version": "3.27.0",
+  "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,6 +1,6 @@
 /* jshint esversion: 11 */
 import { type ReactElement, type ReactNode, useEffect, useState } from "react";
-import { FiBell, FiChevronLeft, FiChevronRight, FiCommand, FiCpu, FiGlobe, FiHash, FiLogOut, FiMessageSquare, FiSearch, FiSettings, FiShield, FiUser } from "react-icons/fi";
+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";
@@ -16,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;
@@ -28,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} />
@@ -43,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;
@@ -52,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);
@@ -64,31 +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;
-      }
-
-      const shortcutQuery = commandPaletteShortcutQuery(event);
-      if (shortcutQuery !== undefined && !isEditableShortcutTarget(event.target)) {
-        event.preventDefault();
-        setCommandInitialQuery(shortcutQuery);
-        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);
@@ -116,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;
@@ -247,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 />,
@@ -300,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

@@ -3,22 +3,26 @@ import { type ReactElement, useCallback, useEffect, useMemo, useRef, useState }
 import { createPortal } from "react-dom";
 import { FiSearch } from "react-icons/fi";
 import { SurfaceGlyph } from "./AppNavigation";
-import type { SurfaceId, SurfaceNavItem } from "./app-model";
-import { orderedNavItems } from "./app-model";
+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;
-  icon: SurfaceNavItem["icon"];
+  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 = 7;
+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" },
@@ -28,13 +32,41 @@ const slashCommandItems: CommandPaletteItem[] = [
   { 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: "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" },
+  { 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 function CommandPalette({ close, initialQuery, openSurface, status }: { close: () => void; initialQuery: string; openSurface: (surface: SurfaceId) => void; status: GuiStatusData }): ReactElement {
-  const allItems = useMemo(() => commandPaletteItems(status), [status]);
+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());
@@ -45,9 +77,12 @@ export function CommandPalette({ close, initialQuery, openSurface, status }: { c
     if (item) {
       const nextRecentIds = rememberCommandPaletteItemId(item.id, recentIds);
       setRecentIds(nextRecentIds);
-      openSurface(item.surface);
+      if (item.action === "copy-current-link") {
+        void copyCurrentSurfaceLink(item.surface);
+      }
+      openItem({ conversationMode: item.conversationMode, shellMode: item.shellMode, surface: item.surface });
     }
-  }, [openSurface, recentIds]);
+  }, [openItem, recentIds]);
 
   useEffect(() => {
     inputRef.current?.focus();
@@ -83,13 +118,13 @@ export function CommandPalette({ close, initialQuery, openSurface, status }: { c
       <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, #sessions, #channels, @people, or /actions" role="combobox" value={query} />
+          <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"><SurfaceGlyph icon={item.icon} /></span>
+                <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>
@@ -106,9 +141,11 @@ export function commandPaletteShortcutQuery(event: Pick<KeyboardEvent, "key" | "
     return undefined;
   }
 
-  return new Map([["/", "/"], ["@", "@"], ["#", "#"], [".", ""]]).get(event.key);
+  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))
@@ -124,12 +161,12 @@ export function rememberCommandPaletteItemId(itemId: string, currentIds: string[
   return nextIds;
 }
 
-function commandPaletteMatches(items: CommandPaletteItem[], query: string, recentIds: string[]): CommandPaletteItem[] {
+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 || ["/", "@", "#"].includes(normalizedQuery)) {
+  if (normalizedQuery.length === 0 || commandPaletteShortcutEntries.some(([shortcut]) => shortcut === normalizedQuery)) {
     return orderCommandItemsByRecency(scopedItems, recentIds).slice(0, 8);
   }
 
@@ -138,7 +175,7 @@ function commandPaletteMatches(items: CommandPaletteItem[], query: string, recen
     .slice(0, 8);
 }
 
-function commandPaletteItems(status: GuiStatusData): CommandPaletteItem[] {
+function commandPaletteItems(status: GuiStatusData, activeSurface: SurfaceId): CommandPaletteItem[] {
   const surfaceItems: CommandPaletteItem[] = orderedNavItems.map((item) => ({
     description: item.description,
     icon: item.icon,
@@ -146,15 +183,24 @@ function commandPaletteItems(status: GuiStatusData): CommandPaletteItem[] {
     label: item.label,
     searchText: `${item.label} ${item.description}`,
     surface: item.id,
-    tag: "Surface",
+    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}`,
+    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[] = [{
@@ -167,20 +213,60 @@ function commandPaletteItems(status: GuiStatusData): CommandPaletteItem[] {
     tag: "Direct message",
   }];
 
-  return [...surfaceItems, ...sessionItems, ...plannedChannelItems, ...directMessageItems, ...slashCommandItems];
+  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"]],
-    ["#", ["AI session", "Channel"]],
+    ["#", ["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);

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

@@ -1352,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.27.0
+# Version: 3.28.0
 #
 # Quick Install:
 #   npm install -g aidevops && aidevops update          (recommended)