aidevops 3.31.13 → 3.31.15

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.31.13-blue.svg)](https://github.com/marcusquinn/aidevops/releases)
+[![Version](https://img.shields.io/badge/Version-3.31.15-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.31.13
+3.31.15

package/aidevops.sh

@@ -5,7 +5,7 @@
 # AI DevOps Framework CLI
 # Usage: aidevops <command> [options]
 #
-# Version: 3.31.13
+# Version: 3.31.15
 
 set -euo pipefail
 
@@ -1126,8 +1126,13 @@ cmd_version() {
 _dispatch_helper() {
 	local script_name="$1" error_name="$2"
 	shift 2
-	local hp="$AGENTS_DIR/scripts/$script_name"
-	[[ ! -f "$hp" ]] && hp="$INSTALL_DIR/.agents/scripts/$script_name"
+	local source_hp="$INSTALL_DIR/.agents/scripts/$script_name"
+	local deployed_hp="$AGENTS_DIR/scripts/$script_name"
+	local hp="$deployed_hp"
+	if [[ -f "$source_hp" && -f "$INSTALL_DIR/.agents/scripts/aidevops-cli/aidevops-repos-lib.sh" ]]; then
+		hp="$source_hp"
+	fi
+	[[ ! -f "$hp" ]] && hp="$source_hp"
 	if [[ -f "$hp" ]]; then
 		bash "$hp" "$@"
 	else
@@ -1712,6 +1717,7 @@ main() {
 			;;
 		esac
 		;;
+	reach) _dispatch_helper "reach-helper.sh" "reach-helper.sh" "$@" ;;
 	config | configure) _dispatch_config "$@" ;;
 	uninstall | remove) cmd_uninstall ;;
 	version | v | -v | --version) cmd_version ;;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aidevops",
-  "version": "3.31.13",
+  "version": "3.31.15",
   "description": "AI DevOps Framework - AI-assisted development workflows, code quality, and deployment automation",
   "type": "module",
   "workspaces": [
@@ -32,6 +32,10 @@
     "gui:test:components": "bun test packages/gui-web/tests",
     "gui:test:security": "bun test packages/gui-shared/tests/security.test.ts packages/gui-api/tests/security.test.ts packages/gui-web/tests/security.test.ts",
     "gui:test:smoke": "bun test packages/gui-api/tests/smoke.test.ts",
+    "gui:lint": "bun test packages/gui-web/tests/security.test.ts packages/gui-shared/tests/security.test.ts packages/gui-api/tests/security.test.ts",
+    "gui:typecheck": "tsc --noEmit",
+    "gui:build": "bun ./node_modules/vite/bin/vite.js build --config packages/gui-web/vite.config.ts",
+    "gui:ci": "npm run gui:lint && npm run gui:typecheck && npm run gui:test:schema && npm run gui:test:adapters && npm run gui:test:api && npm run gui:test:components && npm run gui:test:security && npm run gui:test:smoke && npm run gui:build",
     "gui:desktop:check": "bash packages/gui-desktop/scripts/install-macos-app.sh --check",
     "gui:desktop:install:macos": "bash packages/gui-desktop/scripts/install-macos-app.sh",
     "postinstall": "node scripts/npm-postinstall.cjs || true"

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

@@ -1,6 +1,6 @@
 /* jshint esversion: 11 */
 import { type ReactElement, type ReactNode, useEffect, useState } from "react";
-import { FiAlertTriangle, FiBell, FiCheckCircle, FiChevronLeft, FiChevronRight, FiCommand, FiFileText, FiGlobe, FiHash, FiHelpCircle, FiInfo, FiLogOut, FiMessageSquare, FiPaperclip, FiSearch, FiSettings, FiShield, FiTerminal, FiTool, FiUser } from "react-icons/fi";
+import { FiAlertTriangle, FiBell, FiCheckCircle, FiChevronLeft, FiChevronRight, FiCommand, FiFileText, FiGlobe, FiHash, FiInfo, FiLogOut, FiMap, FiMessageSquare, FiPaperclip, FiSearch, FiSettings, FiShield, FiTerminal, FiTool, FiUser } from "react-icons/fi";
 import type { GuiFileRootId, GuiNotificationSummary, GuiStatusData } from "../../gui-shared/src";
 import { SurfaceGlyph } from "./AppNavigation";
 import type { ConversationMode, ShellMode, SurfaceId, SurfaceNavItem } from "./app-model";
@@ -14,6 +14,7 @@ import { PulseWorkersSurface } from "./PulseWorkersSurface";
 import { AiProvidersSurface, LocalReposSurface, LockedVaultGate, OverviewSurface, PlannedSurface, ProjectsSurface, SecuritySurface, VaultSurface } from "./StatusSurfaces";
 import { isVaultSurfaceLocked, vaultCollectionForSurface } from "./VaultBadges";
 import { applyCommandPaletteSelection, useHeaderMenuState } from "./workspace-header-state";
+import { useWorkspaceTour, WorkspaceTourProvider } from "./WorkspaceTour";
 
 const communityLinks = {
   github: "https://github.com/marcusquinn/aidevops",
@@ -42,12 +43,14 @@ export function Workspace({ activeItem, activeSectionLabel, activeSurface, canGo
 }) {
   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} setConversationMode={setConversationMode} setSelectedLocalRepoIndex={setSelectedLocalRepoIndex} setSelectedSessionId={setSelectedSessionId} setShellMode={setShellMode} status={status} />
-      <div className="workspace-scroll">
-        {shellMode === "sessions"
-          ? <ConversationWorkspace conversationMode={conversationMode} selectedLocalRepoIndex={selectedLocalRepoIndex} selectedSessionId={selectedSessionId} status={status} />
-          : <SurfaceContent activeItem={activeItem} activeSurface={activeSurface} fileRoot={fileRoot} openSurface={setActiveSurface} status={status} />}
-      </div>
+      <WorkspaceTourProvider activeSurface={activeSurface}>
+        <WorkspaceHeader activeItem={activeItem} activeSectionLabel={activeSectionLabel} activeSurface={activeSurface} canGoBack={canGoBack} canGoForward={canGoForward} goBack={goBack} goForward={goForward} setActiveSurface={setActiveSurface} setConversationMode={setConversationMode} setSelectedLocalRepoIndex={setSelectedLocalRepoIndex} setSelectedSessionId={setSelectedSessionId} setShellMode={setShellMode} status={status} />
+        <div className="workspace-scroll">
+          {shellMode === "sessions"
+            ? <ConversationWorkspace conversationMode={conversationMode} selectedLocalRepoIndex={selectedLocalRepoIndex} selectedSessionId={selectedSessionId} status={status} />
+            : <SurfaceContent activeItem={activeItem} activeSurface={activeSurface} fileRoot={fileRoot} openSurface={setActiveSurface} status={status} />}
+        </div>
+      </WorkspaceTourProvider>
     </section>
   );
 }
@@ -73,6 +76,7 @@ function WorkspaceHeader({ activeItem, activeSectionLabel, activeSurface, canGoB
   const userInitials = status.machine.initials || "AI";
   const userName = status.machine.username || "Local user";
   const activeNotifications = status.notifications.filter((notification) => notification.status === "active");
+  const tour = useWorkspaceTour();
 
   useEffect(() => {
     const openCommandPalette = (event: KeyboardEvent) => {
@@ -125,13 +129,14 @@ function WorkspaceHeader({ activeItem, activeSectionLabel, activeSurface, canGoB
       </div>
       <div className="header-actions" onPointerEnter={headerMenus.clearScheduledHeaderClose} onPointerLeave={headerMenus.scheduleHeaderMenusClose} ref={headerMenus.headerActionsRef}>
         <div className="header-action-menu">
-          <button aria-label="Open signposts and help" className="header-icon-button" onClick={() => { headerMenus.closeHeaderMenus(); openItem({ surface: "help" }); }} title="Signposts and help (?)" type="button">
-            <FiHelpCircle aria-hidden="true" />
+          <button aria-disabled={!tour.hasTour} aria-label={tour.hasTour ? `Start ${activeItem.label} tour` : `No tour available for ${activeItem.label}`} className={tour.activeStep ? "header-icon-button active" : "header-icon-button"} disabled={!tour.hasTour} onClick={() => { headerMenus.closeHeaderMenus(); tour.startTour(); }} title={tour.hasTour ? `Start ${activeItem.label} tour` : `No tour available for ${activeItem.label}`} type="button">
+            <FiMap aria-hidden="true" />
           </button>
           <button aria-expanded={headerMenus.notificationsOpen} aria-label="Open notifications" className="header-icon-button" onClick={headerMenus.toggleNotifications} type="button">
             <FiBell aria-hidden="true" />
             {activeNotifications.length > 0 ? <span className="notification-dot" aria-hidden="true" /> : null}
           </button>
+          {tour.activeStep ? <WorkspaceSignposts label={activeItem.label} /> : null}
           {headerMenus.notificationsOpen ? <NotificationsMenu notifications={status.notifications} openSurface={(surface) => openItem({ surface })} /> : null}
         </div>
         <button aria-pressed={headerMenus.assistantOpen} aria-label="Toggle AI Assistant" className={headerMenus.assistantOpen ? "header-icon-button active" : "header-icon-button"} onClick={headerMenus.toggleAssistant} title="AI sessions (_)" type="button">
@@ -150,6 +155,31 @@ function WorkspaceHeader({ activeItem, activeSectionLabel, activeSurface, canGoB
   );
 }
 
+function WorkspaceSignposts({ label }: { label: string }): ReactElement | null {
+  const tour = useWorkspaceTour();
+  const step = tour.activeStep;
+
+  if (!step) {
+    return null;
+  }
+
+  return (
+    <div className="popover-menu signposts-tour" role="dialog" aria-label={`${label} tour`}>
+      <div className="signposts-heading">
+        <strong>{step.title}</strong>
+        <span>{tour.activeStepIndex + 1}/{tour.stepCount}</span>
+      </div>
+      <p>{step.body}</p>
+      <code>{step.target}</code>
+      {tour.missingTarget ? <p className="tour-missing-target">Target is not visible on this page; continuing safely.</p> : null}
+      <div className="signposts-actions">
+        <button onClick={tour.nextStep} type="button">Next</button>
+        <button onClick={tour.closeTour} type="button">Close</button>
+      </div>
+    </div>
+  );
+}
+
 function handleWorkspaceShortcut(event: KeyboardEvent, actions: { goBack: () => void; goForward: () => void; openCommand: (query: string) => void }): void {
   const shortcutQuery = commandPaletteShortcutQuery(event);
   const isEditableTarget = isEditableShortcutTarget(event.target);
@@ -386,9 +416,9 @@ function SurfaceContent({ activeItem, activeSurface, fileRoot, openSurface, stat
     aiSessions: <AiSessionsSurface selectedRepoIndex={0} status={status} />,
     channels: <CommsConversationSurface mode="channels" />,
     directMessages: <CommsConversationSurface mode="directMessages" />,
-    workers: <PulseWorkersSurface status={status} />,
-    repos: <PlannedSurface label={text.repos} detail={text.reposIntro} />,
-    deployments: <PlannedSurface label={text.deployments} detail={text.deploymentsIntro} />,
+    workers: <div data-tour="workers-surface"><PulseWorkersSurface status={status} /></div>,
+    repos: <PlannedSurface label={text.repos} detail={text.reposIntro} tourId="repos-surface" />,
+    deployments: <PlannedSurface label={text.deployments} detail={text.deploymentsIntro} tourId="deployments-surface" />,
     routines: <PlannedSurface label={text.routines} detail={text.routineDetail} />,
     devices: <PlannedSurface label={text.devices} detail={text.devicesIntro} />,
     vpnsProxies: <PlannedSurface label={text.vpnsProxies} detail={text.vpnsProxiesIntro} />,
@@ -474,7 +504,7 @@ function HelpSurface(): ReactElement {
 
 function SettingsSurface({ status }: { status: GuiStatusData }): ReactElement {
   return (
-    <section className="settings-surface">
+    <section className="settings-surface" data-tour="settings-surface">
       <div className="planned-card">
         <h2>General settings</h2>
         <p>{text.settingsAccountIntro}</p>

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

@@ -532,9 +532,9 @@ function isActionablePathRef(pathRef: string): boolean {
   return pathRef.startsWith("~/") || pathRef.startsWith("/");
 }
 
-export function PlannedSurface({ detail, label }: { detail: string; label: string }) {
+export function PlannedSurface({ detail, label, tourId }: { detail: string; label: string; tourId?: string }) {
   return (
-    <section className="panel" aria-label={label}>
+    <section className="panel" aria-label={label} data-tour={tourId}>
       <div className="section-heading">
         <p className="eyebrow">{text.planned}</p>
         <h2>{label}</h2>

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

@@ -0,0 +1,108 @@
+import { createContext, type ReactElement, type ReactNode, useContext, useEffect, useMemo, useState } from "react";
+import type { SurfaceId } from "./app-model";
+
+export interface WorkspaceTourStep {
+  body: string;
+  target: string;
+  title: string;
+}
+
+export type WorkspaceTourRegistry = Partial<Record<SurfaceId, WorkspaceTourStep[]>>;
+
+interface WorkspaceTourContextValue {
+  activeStep: WorkspaceTourStep | undefined;
+  activeStepIndex: number;
+  closeTour: () => void;
+  hasTour: boolean;
+  missingTarget: boolean;
+  nextStep: () => void;
+  startTour: () => void;
+  stepCount: number;
+  steps: WorkspaceTourStep[];
+}
+
+const WorkspaceTourContext = createContext<WorkspaceTourContextValue | undefined>(undefined);
+
+export const workspaceTourRegistry = {
+  aiSessions: [
+    { body: "Choose a local repo/session context before the Turbostarter AI transport adapter is enabled.", target: '[data-tour="ai-session-list"]', title: "Session list" },
+    { body: "Read the current AI transcript, attachments, tool status, and GenUI cards in one MessageScroller-compatible lane.", target: '[data-tour="ai-session-transcript"]', title: "AI transcript" },
+    { body: "The prompt composer is disabled until audited write routes land, but its stable selector is ready for the session bridge.", target: '[data-tour="ai-composer"]', title: "Composer" },
+  ],
+  channels: [
+    { body: "Channels use the shared conversation model and encrypted transport placeholder.", target: '[data-tour="comms-conversations"]', title: "Channel workspace" },
+    { body: "Messages, system events, reactions, and Tambo DevOps cards render through the shared timeline.", target: '[data-tour="comms-message-timeline"]', title: "Channel timeline" },
+  ],
+  directMessages: [
+    { body: "Direct and group DM threads share the same conversation shell as channels.", target: '[data-tour="comms-conversations"]', title: "DM workspace" },
+    { body: "Protected payloads remain read-only until Vault policy and audited transport routes are connected.", target: '[data-tour="comms-message-timeline"]', title: "DM timeline" },
+  ],
+  workers: [
+    { body: "Pulse worker health, systemic findings, and safe diagnostic actions collect on this operational dashboard.", target: '[data-tour="workers-surface"]', title: "Workers dashboard" },
+  ],
+  repos: [
+    { body: "Repository context will connect local and remote repo adapters once audited read/write routes land.", target: '[data-tour="repos-surface"]', title: "Repos" },
+  ],
+  deployments: [
+    { body: "Deployment activity, environments, releases, and rollout checks will appear here after deployment adapters land.", target: '[data-tour="deployments-surface"]', title: "Deployments" },
+  ],
+  settings: [
+    { body: "Account, appearance, language, and notification preferences are grouped here while writes remain disabled.", target: '[data-tour="settings-surface"]', title: "Settings" },
+  ],
+} satisfies WorkspaceTourRegistry;
+
+export function WorkspaceTourProvider({ activeSurface, children, registry = workspaceTourRegistry }: { activeSurface: SurfaceId; children: ReactNode; registry?: WorkspaceTourRegistry }): ReactElement {
+  const steps = registry[activeSurface] ?? [];
+  const [activeStepIndex, setActiveStepIndex] = useState(0);
+  const [isOpen, setIsOpen] = useState(false);
+  const [missingTarget, setMissingTarget] = useState(false);
+  const activeStep = isOpen ? steps[activeStepIndex] : undefined;
+
+  useEffect(() => {
+    const nextSurface = activeSurface;
+    if (!nextSurface) return;
+    setIsOpen(false);
+    setActiveStepIndex(0);
+    setMissingTarget(false);
+  }, [activeSurface]);
+
+  useEffect(() => {
+    if (!activeStep || typeof document === "undefined") {
+      setMissingTarget(false);
+      return;
+    }
+
+    const target = document.querySelector(activeStep.target);
+    setMissingTarget(target === null);
+    if (target instanceof HTMLElement) {
+      target.scrollIntoView({ behavior: "smooth", block: "center" });
+    }
+  }, [activeStep]);
+
+  const value = useMemo(() => ({
+    activeStep,
+    activeStepIndex,
+    closeTour: () => setIsOpen(false),
+    hasTour: steps.length > 0,
+    missingTarget,
+    nextStep: () => setActiveStepIndex((current) => current + 1 >= steps.length ? 0 : current + 1),
+    startTour: () => {
+      if (steps.length === 0) return;
+      setActiveStepIndex(0);
+      setIsOpen(true);
+    },
+    stepCount: steps.length,
+    steps,
+  }), [activeStep, activeStepIndex, missingTarget, steps]);
+
+  return <WorkspaceTourContext.Provider value={value}>{children}</WorkspaceTourContext.Provider>;
+}
+
+export function useWorkspaceTour(): WorkspaceTourContextValue {
+  const context = useContext(WorkspaceTourContext);
+  if (!context) {
+    throw new Error("useWorkspaceTour must be used inside WorkspaceTourProvider");
+  }
+
+  return context;
+}

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

@@ -1364,6 +1364,34 @@ code {
   min-width: 320px;
 }
 
+.signposts-tour {
+  min-width: min(360px, 88vw);
+}
+
+.signposts-heading,
+.signposts-actions {
+  align-items: center;
+  display: flex;
+  justify-content: space-between;
+}
+
+.signposts-heading span {
+  background: var(--surface-muted);
+  border-radius: 999px;
+  color: var(--text-muted);
+  font-size: 0.76rem;
+  font-weight: 900;
+  padding: 4px 8px;
+}
+
+.signposts-tour code {
+  overflow-wrap: anywhere;
+}
+
+.tour-missing-target {
+  color: var(--notification-warning-fg) !important;
+}
+
 .notifications-menu-heading,
 .notification-preview {
   align-items: center;

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.31.13
+# Version: 3.31.15
 #
 # Quick Install:
 #   npm install -g aidevops && aidevops update          (recommended)