@agenticmail/enterprise 0.5.199 → 0.5.201

package/dist/dashboard/pages/agent-detail/overview.js

@@ -3,6 +3,7 @@ import { I } from '../../components/icons.js';
 import { E } from '../../assets/icons/emoji-icons.js';
 import { Badge, StatCard, EmptyState, formatNumber, formatCost, formatTime, MEMORY_CATEGORIES, memCatColor, memCatLabel, importanceBadgeColor } from './shared.js?v=4';
 import { resolveManager } from './manager.js?v=4';
+import { HelpButton } from '../../components/help-button.js';
 
 var CATEGORY_COLORS = {
   code_of_conduct: '#6366f1', communication: '#0ea5e9', data_handling: '#f59e0b',
@@ -118,17 +119,17 @@ export function OverviewSection(props) {
       .finally(function() { setActing(''); });
   };
 
-  // Triple-confirmation delete flow
-  var [deleteStep, setDeleteStep] = useState(0); // 0=hidden, 1=first, 2=second, 3=type-name
+  // 5-step confirmation delete flow
+  var [deleteStep, setDeleteStep] = useState(0); // 0=hidden, 1-5=steps
   var [deleteTyped, setDeleteTyped] = useState('');
+  var [deleteChecked, setDeleteChecked] = useState(false);
 
-  var startDelete = function() { setDeleteStep(1); setDeleteTyped(''); };
-  var cancelDelete = function() { setDeleteStep(0); setDeleteTyped(''); };
+  var startDelete = function() { setDeleteStep(1); setDeleteTyped(''); setDeleteChecked(false); };
+  var cancelDelete = function() { setDeleteStep(0); setDeleteTyped(''); setDeleteChecked(false); };
 
   var advanceDelete = async function() {
-    if (deleteStep === 1) { setDeleteStep(2); return; }
-    if (deleteStep === 2) { setDeleteStep(3); return; }
-    if (deleteStep === 3) {
+    if (deleteStep < 5) { setDeleteStep(deleteStep + 1); setDeleteChecked(false); return; }
+    if (deleteStep === 5) {
       var expectedName = (engineAgent?.name || '').trim().toLowerCase();
       if (deleteTyped.trim().toLowerCase() !== expectedName) {
         toast('Agent name does not match', 'error');
@@ -185,6 +186,11 @@ export function OverviewSection(props) {
     return h('div', { style: { padding: 40, textAlign: 'center', color: 'var(--text-muted)' } }, 'Loading overview...');
   }
 
+  // Help tooltip styles
+  var _h4 = { marginTop: 16, marginBottom: 8, fontSize: 14 };
+  var _ul = { paddingLeft: 20, margin: '4px 0 8px' };
+  var _tip = { marginTop: 12, padding: 12, background: 'var(--bg-secondary, #1e293b)', borderRadius: 'var(--radius, 8px)', fontSize: 13 };
+
   return h(Fragment, null,
 
     // ─── Agent Summary Card ─────────────────────────────
@@ -227,6 +233,21 @@ export function OverviewSection(props) {
     ),
 
     // ─── Stats Grid ─────────────────────────────────────
+    h('div', { style: { display: 'flex', alignItems: 'center', gap: 4, marginBottom: 8 } },
+      h('div', { style: { fontSize: 13, fontWeight: 600, color: 'var(--text-muted)', textTransform: 'uppercase', letterSpacing: '0.05em' } }, 'Today\'s Usage'),
+      h(HelpButton, { label: 'Today\'s Usage Stats' },
+        h('p', null, 'Real-time performance metrics for this agent over the current day (UTC).'),
+        h('h4', { style: _h4 }, 'Metrics Explained'),
+        h('ul', { style: _ul },
+          h('li', null, h('strong', null, 'Tokens Today'), ' — Total input + output tokens consumed by the LLM. Higher token usage means more complex conversations or longer outputs.'),
+          h('li', null, h('strong', null, 'Cost Today'), ' — Estimated API cost based on token usage and the agent\'s configured model pricing.'),
+          h('li', null, h('strong', null, 'Uptime'), ' — How long the agent has been running since last restart. Resets when the engine restarts.'),
+          h('li', null, h('strong', null, 'Error Rate'), ' — Percentage of requests that resulted in errors (timeouts, API failures, guardrail blocks). Above 5% is flagged in red.'),
+          h('li', null, h('strong', null, 'Active Sessions'), ' — Currently open conversation sessions. Each chat, email thread, or task is a separate session.')
+        ),
+        h('div', { style: _tip }, h('strong', null, 'Tip: '), 'If cost is climbing faster than expected, check the Budget tab to set daily/monthly spending limits.')
+      )
+    ),
     h('div', { className: 'stat-grid', style: { marginBottom: 20 } },
       h(StatCard, { label: 'Tokens Today', value: formatNumber(tokensToday) }),
       h(StatCard, { label: 'Cost Today', value: formatCost(costToday) }),
@@ -240,7 +261,18 @@ export function OverviewSection(props) {
 
       // Onboarding Status
       h('div', { className: 'card' },
-        h('div', { className: 'card-header' }, h('span', null, 'Onboarding')),
+        h('div', { className: 'card-header' }, h('span', { style: { display: 'flex', alignItems: 'center' } }, 'Onboarding',
+          h(HelpButton, { label: 'Agent Onboarding' },
+            h('p', null, 'Onboarding ensures the agent acknowledges your organization\'s policies, guardrails, and code of conduct before it starts working.'),
+            h('h4', { style: _h4 }, 'How It Works'),
+            h('ul', { style: _ul },
+              h('li', null, 'When initiated, the agent reads and acknowledges each policy you\'ve configured in Guardrails.'),
+              h('li', null, 'The agent must complete onboarding before it can process tasks.'),
+              h('li', null, '"Force Complete" skips the acknowledgement process — use this for agents that don\'t need formal onboarding.')
+            ),
+            h('div', { style: _tip }, h('strong', null, 'Tip: '), 'Set up your guardrail policies first (Guardrails tab), then onboard the agent. The agent will reference these policies in every interaction.')
+          )
+        )),
         h('div', { className: 'card-body' },
           h('div', { style: { display: 'flex', alignItems: 'center', gap: 8, marginBottom: 12 } },
             onboardingStatus?.onboarded
@@ -280,7 +312,19 @@ export function OverviewSection(props) {
 
       // Guardrails Status
       h('div', { className: 'card' },
-        h('div', { className: 'card-header' }, h('span', null, 'Guardrails')),
+        h('div', { className: 'card-header' }, h('span', { style: { display: 'flex', alignItems: 'center' } }, 'Guardrails',
+          h(HelpButton, { label: 'Guardrails Status' },
+            h('p', null, 'Guardrails are safety rules that constrain the agent\'s behavior. When active, the agent is monitored and can be automatically paused if it violates a policy.'),
+            h('h4', { style: _h4 }, 'States'),
+            h('ul', { style: _ul },
+              h('li', null, h('strong', null, 'Active'), ' — The agent is running normally with all guardrails enforced.'),
+              h('li', null, h('strong', null, 'Paused'), ' — The agent has been paused (manually or by an automated trigger). It will not process new tasks until resumed.')
+            ),
+            h('h4', { style: _h4 }, 'Interventions'),
+            h('p', null, 'The intervention count tracks how many times a guardrail rule has triggered (e.g., blocked a response, flagged content, or paused the agent). High counts may indicate the agent needs reconfiguration.'),
+            h('div', { style: _tip }, h('strong', null, 'Tip: '), 'Configure guardrail policies in the Guardrails tab. Use "pause" triggers for critical rules and "log" triggers for monitoring.')
+          )
+        )),
         h('div', { className: 'card-body' },
           h('div', { style: { display: 'flex', alignItems: 'center', gap: 8, marginBottom: 12 } },
             guardrailStatus?.paused
@@ -295,7 +339,17 @@ export function OverviewSection(props) {
 
       // Workforce Status
       h('div', { className: 'card' },
-        h('div', { className: 'card-header' }, h('span', null, 'Workforce')),
+        h('div', { className: 'card-header' }, h('span', { style: { display: 'flex', alignItems: 'center' } }, 'Workforce',
+          h(HelpButton, { label: 'Workforce Status' },
+            h('p', null, 'Workforce management tracks the agent\'s work schedule and availability, similar to an employee clocking in and out.'),
+            h('h4', { style: _h4 }, 'Clock In / Clock Out'),
+            h('ul', { style: _ul },
+              h('li', null, h('strong', null, 'Clocked In'), ' — The agent is on duty and will process incoming tasks, messages, and emails.'),
+              h('li', null, h('strong', null, 'Clocked Out'), ' — The agent is off duty. Depending on configuration, tasks may queue until the agent clocks back in.')
+            ),
+            h('div', { style: _tip }, h('strong', null, 'Tip: '), 'Set up automatic schedules in the Workforce tab so agents clock in/out at specific times (e.g., business hours only).')
+          )
+        )),
         h('div', { className: 'card-body' },
           h('div', { style: { display: 'flex', alignItems: 'center', gap: 8, marginBottom: 12 } },
             workforceStatus?.clockedIn
@@ -312,7 +366,20 @@ export function OverviewSection(props) {
     // ─── Real-Time Status Card ────────────────────────────
     h('div', { className: 'card', style: { marginBottom: 20 } },
       h('div', { className: 'card-header', style: { display: 'flex', justifyContent: 'space-between', alignItems: 'center' } },
-        h('span', null, 'Live Status'),
+        h('span', { style: { display: 'flex', alignItems: 'center' } }, 'Live Status',
+          h(HelpButton, { label: 'Live Status' },
+            h('p', null, 'Real-time status streamed via Server-Sent Events (SSE). Updates automatically without refreshing the page.'),
+            h('h4', { style: _h4 }, 'Status Indicators'),
+            h('ul', { style: _ul },
+              h('li', null, h('strong', null, 'Online'), ' — Agent is running and processing requests normally.'),
+              h('li', null, h('strong', null, 'Idle'), ' — Agent is running but not currently processing any task.'),
+              h('li', null, h('strong', null, 'Busy'), ' — Agent is actively processing a request or task.'),
+              h('li', null, h('strong', null, 'Error'), ' — Agent encountered an issue. Check the Activity tab for details.')
+            ),
+            h('p', null, 'The current task, model, and token count are shown when the agent is actively working.'),
+            h('div', { style: _tip }, h('strong', null, 'Tip: '), 'If the status shows "offline" but the agent should be running, try restarting from Quick Actions.')
+          )
+        ),
         rtStatus ? h('span', {
           className: 'badge badge-' + (rtStatus.status === 'online' ? 'success' : rtStatus.status === 'idle' ? 'info' : rtStatus.status === 'error' ? 'danger' : 'neutral'),
           style: { textTransform: 'capitalize' }
@@ -353,7 +420,18 @@ export function OverviewSection(props) {
 
     // ─── Quick Actions Bar ──────────────────────────────
     h('div', { className: 'card', style: { marginBottom: 20 } },
-      h('div', { className: 'card-header' }, h('span', null, 'Quick Actions')),
+      h('div', { className: 'card-header' }, h('span', { style: { display: 'flex', alignItems: 'center' } }, 'Quick Actions',
+        h(HelpButton, { label: 'Quick Actions' },
+          h('p', null, 'Common agent operations you can perform directly from the overview.'),
+          h('ul', { style: _ul },
+            h('li', null, h('strong', null, 'Pause / Resume'), ' — Temporarily stop the agent from processing tasks. Existing sessions are preserved.'),
+            h('li', null, h('strong', null, 'Clock In / Out'), ' — Toggle the agent\'s workforce availability.'),
+            h('li', null, h('strong', null, 'Restart'), ' — Restart the agent\'s engine if it\'s stuck or behaving unexpectedly.'),
+            h('li', null, h('strong', null, 'Redeploy'), ' — Re-deploy with the latest configuration changes.')
+          ),
+          h('div', { style: _tip }, h('strong', null, 'Tip: '), 'Pause is instant and safe — it doesn\'t lose any context. Use it when you need to make config changes.')
+        )
+      )),
       h('div', { className: 'card-body', style: { display: 'flex', flexWrap: 'wrap', gap: 10 } },
 
         // Reset state (when in error/degraded)
@@ -437,35 +515,95 @@ export function OverviewSection(props) {
 
     // ─── Triple Confirmation Modals ───────────────────────
     deleteStep >= 1 && h('div', { className: 'modal-overlay', onClick: cancelDelete },
-      h('div', { className: 'modal', onClick: function(e) { e.stopPropagation(); }, style: { width: 440 } },
+      h('div', { className: 'modal', onClick: function(e) { e.stopPropagation(); }, style: { width: 480 } },
         h('div', { className: 'modal-header' },
           h('h2', { style: { color: 'var(--danger)' } },
-            deleteStep === 1 ? 'Are you sure?' : deleteStep === 2 ? 'This is irreversible' : 'Final confirmation'
+            ['', 'Step 1: Are you sure?', 'Step 2: Data Loss Warning', 'Step 3: Memory & Knowledge Loss', 'Step 4: Communication & Integration Impact', 'Step 5: Final Confirmation'][deleteStep]
           ),
           h('button', { className: 'btn btn-ghost btn-icon', onClick: cancelDelete }, '\u00D7')
         ),
+        // Step indicator
+        h('div', { style: { display: 'flex', gap: 4, padding: '0 20px', paddingTop: 12 } },
+          [1,2,3,4,5].map(function(s) {
+            return h('div', { key: s, style: { flex: 1, height: 4, borderRadius: 2, background: s <= deleteStep ? 'var(--danger)' : 'var(--border)' } });
+          })
+        ),
         h('div', { className: 'modal-body', style: { padding: 20 } },
+
+          // Step 1 — Initial warning
           deleteStep === 1 && h(Fragment, null,
             h('p', { style: { marginBottom: 12 } }, 'You are about to delete agent ', h('strong', null, engineAgent?.name || agentId), '.'),
-            h('p', { style: { color: 'var(--text-muted)', fontSize: 13 } }, 'This will permanently remove the agent, all sessions, memory, and configuration. There is no way to recover this data.'),
+            h('p', { style: { color: 'var(--text-muted)', fontSize: 13, marginBottom: 12 } }, 'This is a destructive action that will permanently remove this agent and everything associated with it. There is no undo, no recycle bin, and no way to recover.'),
+            h('p', { style: { fontSize: 13 } }, 'Please proceed through the next steps to understand exactly what will be lost.'),
             h('div', { style: { display: 'flex', gap: 8, marginTop: 20, justifyContent: 'flex-end' } },
               h('button', { className: 'btn btn-secondary', onClick: cancelDelete }, 'Cancel'),
-              h('button', { className: 'btn btn-danger', onClick: advanceDelete }, 'Yes, I want to delete')
+              h('button', { className: 'btn btn-danger', onClick: advanceDelete }, 'I understand, continue')
             )
           ),
+
+          // Step 2 — Data loss
           deleteStep === 2 && h(Fragment, null,
             h('div', { style: { background: 'var(--danger-soft)', border: '1px solid var(--danger)', borderRadius: 'var(--radius)', padding: 12, marginBottom: 16 } },
-              h('strong', { style: { color: 'var(--danger)' } }, 'WARNING: '),
-              h('span', null, 'All data for this agent will be permanently destroyed including emails, conversations, memory entries, tool logs, and configurations.')
+              h('strong', { style: { color: 'var(--danger)', display: 'block', marginBottom: 6 } }, 'ALL AGENT DATA WILL BE DESTROYED'),
+              h('ul', { style: { margin: '4px 0 0', paddingLeft: 18, fontSize: 13 } },
+                h('li', null, 'All email messages (inbox, sent, drafts, folders)'),
+                h('li', null, 'All conversation sessions and chat history'),
+                h('li', null, 'All tool execution logs and audit trails'),
+                h('li', null, 'All configuration, settings, and deployment config'),
+                h('li', null, 'All scheduled jobs, cron tasks, and automations')
+              )
             ),
-            h('p', { style: { marginBottom: 8 } }, 'This action ', h('strong', null, 'CANNOT'), ' be undone. Are you absolutely sure?'),
+            h('p', { style: { fontSize: 13, color: 'var(--text-muted)' } }, 'If you need any of this data, export it BEFORE proceeding.'),
             h('div', { style: { display: 'flex', gap: 8, marginTop: 20, justifyContent: 'flex-end' } },
               h('button', { className: 'btn btn-secondary', onClick: cancelDelete }, 'Cancel'),
-              h('button', { className: 'btn btn-danger', onClick: advanceDelete }, 'I understand, continue')
+              h('button', { className: 'btn btn-danger', onClick: advanceDelete }, 'Continue anyway')
             )
           ),
+
+          // Step 3 — Memory & knowledge loss
           deleteStep === 3 && h(Fragment, null,
-            h('p', { style: { marginBottom: 12 } }, 'To confirm, type the agent name ', h('strong', { style: { fontFamily: 'var(--font-mono)', background: 'var(--bg-tertiary)', padding: '2px 6px', borderRadius: 4 } }, engineAgent?.name || agentId), ' below:'),
+            h('div', { style: { background: 'var(--danger-soft)', border: '1px solid var(--danger)', borderRadius: 'var(--radius)', padding: 12, marginBottom: 16 } },
+              h('strong', { style: { color: 'var(--danger)', display: 'block', marginBottom: 6 } }, 'MEMORY & KNOWLEDGE PERMANENTLY LOST'),
+              h('ul', { style: { margin: '4px 0 0', paddingLeft: 18, fontSize: 13 } },
+                h('li', null, 'All long-term memory entries the agent has built over time'),
+                h('li', null, 'All learned preferences, patterns, and behavioral adaptations'),
+                h('li', null, 'All knowledge base contributions and embeddings'),
+                h('li', null, 'All training data, fine-tuning, and custom instructions'),
+                h('li', null, 'The agent\'s entire personality and relationship context')
+              )
+            ),
+            h('p', { style: { fontSize: 13, color: 'var(--text-muted)' } }, 'This agent has been learning and building context. Once deleted, this knowledge cannot be reconstructed even if you create a new agent with the same name.'),
+            h('div', { style: { display: 'flex', gap: 8, marginTop: 20, justifyContent: 'flex-end' } },
+              h('button', { className: 'btn btn-secondary', onClick: cancelDelete }, 'Cancel'),
+              h('button', { className: 'btn btn-danger', onClick: advanceDelete }, 'Continue anyway')
+            )
+          ),
+
+          // Step 4 — Communication & integration impact
+          deleteStep === 4 && h(Fragment, null,
+            h('div', { style: { background: 'var(--danger-soft)', border: '1px solid var(--danger)', borderRadius: 'var(--radius)', padding: 12, marginBottom: 16 } },
+              h('strong', { style: { color: 'var(--danger)', display: 'block', marginBottom: 6 } }, 'COMMUNICATION & INTEGRATION IMPACT'),
+              h('ul', { style: { margin: '4px 0 0', paddingLeft: 18, fontSize: 13 } },
+                h('li', null, 'The agent\'s email address will stop working immediately'),
+                h('li', null, 'Any external services or APIs relying on this agent will break'),
+                h('li', null, 'Other agents that communicate with this agent will lose their connection'),
+                h('li', null, 'Active workflows, approval chains, and escalation paths will be disrupted'),
+                h('li', null, 'Contacts and external parties will receive bounced emails')
+              )
+            ),
+            h('p', { style: { fontSize: 13, color: 'var(--text-muted)' } }, 'If this agent is part of a team or workflow, consider reassigning its responsibilities first.'),
+            h('div', { style: { display: 'flex', gap: 8, marginTop: 20, justifyContent: 'flex-end' } },
+              h('button', { className: 'btn btn-secondary', onClick: cancelDelete }, 'Cancel'),
+              h('button', { className: 'btn btn-danger', onClick: advanceDelete }, 'I accept the consequences')
+            )
+          ),
+
+          // Step 5 — Type name to confirm
+          deleteStep === 5 && h(Fragment, null,
+            h('div', { style: { background: 'var(--danger-soft)', border: '1px solid var(--danger)', borderRadius: 'var(--radius)', padding: 12, marginBottom: 16, textAlign: 'center' } },
+              h('strong', { style: { color: 'var(--danger)', fontSize: 15 } }, 'THIS ACTION IS PERMANENT AND IRREVERSIBLE')
+            ),
+            h('p', { style: { marginBottom: 12 } }, 'To confirm deletion, type the agent name ', h('strong', { style: { fontFamily: 'var(--font-mono)', background: 'var(--bg-tertiary)', padding: '2px 6px', borderRadius: 4 } }, engineAgent?.name || agentId), ' below:'),
             h('input', {
               type: 'text',
               className: 'form-control',

package/dist/dashboard/pages/agent-detail/permissions.js

@@ -1,6 +1,7 @@
 import { h, useState, useEffect, useCallback, Fragment, useApp, apiCall, engineCall, formatUptime, buildAgentDataMap, renderAgentBadge, showConfirm, getOrgId } from '../../components/utils.js';
 import { I } from '../../components/icons.js';
 import { Badge, EmptyState, riskBadgeClass } from './shared.js?v=4';
+import { HelpButton } from '../../components/help-button.js';
 
 // ════════════════════════════════════════════════════════════
 // PERMISSIONS SECTION
@@ -350,7 +351,10 @@ export function PermissionsSection(props) {
 
   var soulCard = h('div', { className: 'card', style: { marginBottom: 20 } },
     h('div', { className: 'card-header', style: { cursor: 'pointer', display: 'flex', justifyContent: 'space-between', alignItems: 'center', userSelect: 'none' }, onClick: function() { setSoulOpen(!soulOpen); } },
-      h('span', null, 'Role Templates'),
+      h('span', { style: { display: 'flex', alignItems: 'center' } }, 'Role Templates', h(HelpButton, { label: 'Role Templates' },
+        h('p', null, 'Pre-configured agent personas with identity, personality, skills, and permissions bundled together. Applying a template sets up the agent for a specific role in one click.'),
+        h('div', { style: { marginTop: 12, padding: 12, background: 'var(--bg-secondary, #1e293b)', borderRadius: 'var(--radius, 8px)', fontSize: 13 } }, h('strong', null, 'Tip: '), 'Role templates are a great starting point. You can always customize individual settings after applying one.')
+      )),
       h('span', { style: { fontSize: 11, color: 'var(--text-muted)', display: 'flex', alignItems: 'center', gap: 6 } },
         h('span', null, Object.values(soulCategories).reduce(function(sum, arr) { return sum + arr.length; }, 0) + ' templates'),
         h('span', { style: { transition: 'transform 0.2s', transform: soulOpen ? 'rotate(180deg)' : 'rotate(0deg)', display: 'inline-block', lineHeight: 1 } },
@@ -393,7 +397,14 @@ export function PermissionsSection(props) {
 
   // Preset selector card (always visible)
   var presetCard = h('div', { className: 'card', style: { marginBottom: 20 } },
-    h('div', { className: 'card-header' }, h('span', null, 'Apply a Permission Preset')),
+    h('div', { className: 'card-header' }, h('span', { style: { display: 'flex', alignItems: 'center' } }, 'Apply a Permission Preset', h(HelpButton, { label: 'Permission Presets' },
+      h('p', null, 'Quick permission profiles that configure risk levels, blocked actions, rate limits, and approval requirements. Presets replace the current permission profile entirely.'),
+      h('ul', { style: { paddingLeft: 20, margin: '4px 0 8px' } },
+        h('li', null, h('strong', null, 'Restrictive'), ' — Low risk, many blocked actions, approval required.'),
+        h('li', null, h('strong', null, 'Standard'), ' — Balanced defaults for most agents.'),
+        h('li', null, h('strong', null, 'Permissive'), ' — High autonomy, fewer restrictions.')
+      )
+    ))),
     h('div', { className: 'card-body' },
       h('p', { style: { fontSize: 12, color: 'var(--text-muted)', marginBottom: 12 } }, 'Select a preset to quickly configure this agent\'s permissions. This will replace the current profile.'),
       presets.length > 0
@@ -459,7 +470,9 @@ export function PermissionsSection(props) {
     // ─── Current Profile + Edit Button ──────────────────
     h('div', { className: 'card', style: { marginBottom: 20 } },
       h('div', { className: 'card-header', style: { display: 'flex', justifyContent: 'space-between', alignItems: 'center' } },
-        h('span', null, 'Current Permission Profile'),
+        h('span', { style: { display: 'flex', alignItems: 'center' } }, 'Current Permission Profile', h(HelpButton, { label: 'Permission Profile' },
+          h('p', null, 'The active permission profile controls what this agent can do. It defines the maximum risk level, blocked side effects, sandbox mode, and approval requirements.')
+        )),
         h('button', { className: 'btn btn-primary btn-sm', onClick: startEdit }, I.journal(), ' Edit')
       ),
       h('div', { className: 'card-body' },
@@ -484,7 +497,9 @@ export function PermissionsSection(props) {
 
     // ─── Approval Settings Card ─────────────────────────
     h('div', { className: 'card', style: { marginBottom: 20 } },
-      h('div', { className: 'card-header' }, h('span', null, 'Approval Settings')),
+      h('div', { className: 'card-header' }, h('span', { style: { display: 'flex', alignItems: 'center' } }, 'Approval Settings', h(HelpButton, { label: 'Approval Settings' },
+        h('p', null, 'When enabled, the agent must get human approval before performing risky actions. You can configure which risk levels and side effects trigger approval, and how long to wait before timing out.')
+      ))),
       h('div', { className: 'card-body' },
         h('div', { style: { display: 'flex', alignItems: 'center', gap: 12, marginBottom: 16 } },
           h('span', { style: { fontSize: 13, color: 'var(--text-secondary)' } }, 'Approval Required:'),
@@ -514,7 +529,9 @@ export function PermissionsSection(props) {
 
     // ─── Rate Limits Card ───────────────────────────────
     h('div', { className: 'card', style: { marginBottom: 20 } },
-      h('div', { className: 'card-header' }, h('span', null, 'Rate Limits')),
+      h('div', { className: 'card-header' }, h('span', { style: { display: 'flex', alignItems: 'center' } }, 'Rate Limits', h(HelpButton, { label: 'Rate Limits' },
+        h('p', null, 'Controls how many tool calls the agent can make per time period. Prevents runaway behavior and controls costs. External actions (email, messaging) have a separate limit.')
+      ))),
       h('div', { className: 'card-body' },
         h('div', { style: { display: 'grid', gridTemplateColumns: '1fr 1fr', gap: 16 } },
           h('div', { style: { padding: 12, background: 'var(--bg-tertiary)', borderRadius: 8 } }, h('div', { style: { fontSize: 11, color: 'var(--text-muted)', marginBottom: 4 } }, 'Calls / Minute'), h('div', { style: { fontSize: 20, fontWeight: 700 } }, String(callsPerMin || 'Unlimited'))),
@@ -527,7 +544,9 @@ export function PermissionsSection(props) {
 
     // ─── Constraints Card ───────────────────────────────
     h('div', { className: 'card', style: { marginBottom: 20 } },
-      h('div', { className: 'card-header' }, h('span', null, 'Constraints')),
+      h('div', { className: 'card-header' }, h('span', { style: { display: 'flex', alignItems: 'center' } }, 'Constraints', h(HelpButton, { label: 'Constraints' },
+        h('p', null, 'Operational limits for concurrent tasks, session duration, sandbox mode, and IP allowlisting. These prevent the agent from consuming excessive resources.')
+      ))),
       h('div', { className: 'card-body' },
         h('div', { style: { display: 'grid', gridTemplateColumns: '1fr 1fr', gap: 16 } },
           h('div', null, h('div', { style: { fontSize: 12, color: 'var(--text-muted)', marginBottom: 4 } }, 'Max Concurrent Tasks'), h('div', { style: { fontSize: 14, fontWeight: 600 } }, String(maxConcurrent))),
@@ -555,7 +574,9 @@ export function PermissionsSection(props) {
 
     // ─── Applicable Policies Table ──────────────────────
     h('div', { className: 'card', style: { marginBottom: 20 } },
-      h('div', { className: 'card-header' }, h('span', null, 'Applicable Policies')),
+      h('div', { className: 'card-header' }, h('span', { style: { display: 'flex', alignItems: 'center' } }, 'Applicable Policies', h(HelpButton, { label: 'Applicable Policies' },
+        h('p', null, 'Organization-level policies that apply to this agent. Policies define rules of conduct, data handling requirements, brand voice guidelines, and escalation procedures. Mandatory policies are enforced; recommended and informational policies are advisory.')
+      ))),
       policies.length > 0
         ? h('div', { className: 'card-body-flush' },
             h('table', { className: 'data-table' },

package/dist/dashboard/pages/agent-detail/personal-details.js

@@ -2,6 +2,7 @@ import { h, useState, useEffect, useCallback, Fragment, useApp, apiCall, engineC
 import { I } from '../../components/icons.js';
 import { E } from '../../assets/icons/emoji-icons.js';
 import { TimezoneSelect } from '../../components/timezones.js';
+import { HelpButton } from '../../components/help-button.js';
 import { CULTURES, LANGUAGES, DEFAULT_TRAITS, computeAge, PersonaForm } from '../../components/persona-fields.js';
 import { TagInput } from '../../components/tag-input.js';
 import { Badge, StatCard, formatTime } from './shared.js?v=4';
@@ -143,7 +144,22 @@ export function PersonalDetailsSection(props) {
     return h(Fragment, null,
       // Header with Edit button
       h('div', { style: { display: 'flex', justifyContent: 'space-between', alignItems: 'center', marginBottom: 20 } },
-        h('h3', { style: { margin: 0, fontSize: 16, fontWeight: 600 } }, 'Personal Details'),
+        h('h3', { style: { margin: 0, fontSize: 16, fontWeight: 600, display: 'flex', alignItems: 'center' } }, 'Personal Details',
+          h(HelpButton, { label: 'Personal Details' },
+            h('p', null, 'Define who this agent is — its name, role, personality, and how it presents itself to the world.'),
+            h('h4', { style: { marginTop: 16, marginBottom: 8, fontSize: 14 } }, 'Fields'),
+            h('ul', { style: { paddingLeft: 20, margin: '4px 0 8px' } },
+              h('li', null, h('strong', null, 'Name'), ' — The agent\'s display name. Used in emails, chat messages, and team interactions.'),
+              h('li', null, h('strong', null, 'Role'), ' — Job title or function (e.g., "Sales Rep", "Support Agent"). Helps the agent understand its responsibilities.'),
+              h('li', null, h('strong', null, 'Timezone'), ' — Used for scheduling, work hours, and time-aware responses.'),
+              h('li', null, h('strong', null, 'Avatar'), ' — Profile image shown in chat, emails, and the dashboard.'),
+              h('li', null, h('strong', null, 'Personality Traits'), ' — Adjectives that shape the agent\'s tone and style (e.g., "professional", "friendly", "concise").'),
+              h('li', null, h('strong', null, 'Communication Style'), ' — How the agent writes: formal, casual, technical, etc.'),
+              h('li', null, h('strong', null, 'Backstory'), ' — Optional narrative context that enriches the agent\'s persona.')
+            ),
+            h('div', { style: { marginTop: 12, padding: 12, background: 'var(--bg-secondary, #1e293b)', borderRadius: 'var(--radius, 8px)', fontSize: 13 } }, h('strong', null, 'Tip: '), 'Personality traits have a real impact on output quality. Agents with clear traits produce more consistent, on-brand communications.')
+          )
+        ),
         h('button', { className: 'btn btn-primary btn-sm', onClick: startEdit }, I.journal(), ' Edit Details')
       ),
 

package/dist/dashboard/pages/agent-detail/security.js

@@ -2,6 +2,7 @@ import { h, useState, useEffect, Fragment, useApp, apiCall } from '../../compone
 import { I } from '../../components/icons.js';
 import { E } from '../../assets/icons/emoji-icons.js';
 import { Badge, StatCard, EmptyState } from './shared.js?v=5';
+import { HelpButton } from '../../components/help-button.js';
 
 export function AgentSecurityTab(props) {
   var agentId = props.agentId;
@@ -178,7 +179,14 @@ export function AgentSecurityTab(props) {
   return h('div', null,
     h('div', { style: { display: 'flex', alignItems: 'center', justifyContent: 'space-between', marginBottom: 24 } },
       h('div', null,
-        h('h2', { style: { fontSize: 18, fontWeight: 700, margin: 0 } }, 'Agent Security Settings'),
+        h('h2', { style: { fontSize: 18, fontWeight: 700, margin: 0, display: 'flex', alignItems: 'center' } }, 'Agent Security Settings', h(HelpButton, { label: 'Agent Security' },
+          h('p', null, 'Configure security defenses specific to this agent. Each section can use the global (organization-wide) settings or be customized with agent-specific overrides.'),
+          h('ul', { style: { paddingLeft: 20, margin: '4px 0 8px' } },
+            h('li', null, h('strong', null, 'GLOBAL badge'), ' — Using organization defaults. Toggle the switch to customize.'),
+            h('li', null, h('strong', null, 'Custom'), ' — Agent-specific override is active.')
+          ),
+          h('div', { style: { marginTop: 12, padding: 12, background: 'var(--bg-secondary, #1e293b)', borderRadius: 'var(--radius, 8px)', fontSize: 13 } }, h('strong', null, 'Tip: '), 'Only override settings for agents that need different security levels. For most agents, the global defaults are sufficient.')
+        )),
         h('p', { style: { fontSize: 14, color: 'var(--text-muted)', margin: '4px 0 0' } }, 'Configure security overrides specific to this agent')
       ),
       h('button', {
@@ -191,7 +199,9 @@ export function AgentSecurityTab(props) {
 
     // Prompt Injection Defense
     h('div', { style: _cardStyle },
-      h('div', { style: _cardTitleStyle }, I.shield(), 'Prompt Injection Defense'),
+      h('div', { style: _cardTitleStyle }, I.shield(), 'Prompt Injection Defense', h(HelpButton, { label: 'Prompt Injection Defense' },
+        h('p', null, 'Detects and prevents prompt injection attacks — where malicious input tries to override the agent\'s instructions. Choose between monitoring (log only), sanitizing (strip dangerous content), or blocking (reject entirely).')
+      )),
       h('p', { style: _cardDescStyle }, 'Multi-layer detection and prevention of prompt injection attacks'),
       h(GlobalToggle, { section: 'promptInjection', label: 'Prompt Injection Defense' }),
       !useGlobal.promptInjection && (function() {
@@ -236,7 +246,9 @@ export function AgentSecurityTab(props) {
 
     // SQL Injection Prevention
     h('div', { style: _cardStyle },
-      h('div', { style: _cardTitleStyle }, I.shield(), 'SQL Injection Prevention'),
+      h('div', { style: _cardTitleStyle }, I.shield(), 'SQL Injection Prevention', h(HelpButton, { label: 'SQL Injection Prevention' },
+        h('p', null, 'Scans tool arguments and API requests for SQL injection patterns. Prevents agents from being tricked into executing malicious database queries.')
+      )),
       h('p', { style: _cardDescStyle }, 'Detect and block SQL injection attempts'),
       h(GlobalToggle, { section: 'sqlInjection', label: 'SQL Injection Prevention' }),
       !useGlobal.sqlInjection && (function() {
@@ -287,7 +299,9 @@ export function AgentSecurityTab(props) {
 
     // Output Filtering
     h('div', { style: _cardStyle },
-      h('div', { style: _cardTitleStyle }, I.shield(), 'Output Filtering'),
+      h('div', { style: _cardTitleStyle }, I.shield(), 'Output Filtering', h(HelpButton, { label: 'Output Filtering' },
+        h('p', null, 'Scans agent responses for leaked secrets (API keys, passwords) and personally identifiable information (PII). Can monitor, redact, or block outputs containing sensitive data.')
+      )),
       h('p', { style: _cardDescStyle }, 'Scan agent outputs for secrets and personal information'),
       h(GlobalToggle, { section: 'outputFiltering', label: 'Output Filtering' }),
       !useGlobal.outputFiltering && (function() {
@@ -339,7 +353,9 @@ export function AgentSecurityTab(props) {
 
     // Security Audit Log
     h('div', { style: _cardStyle },
-      h('div', { style: _cardTitleStyle }, I.journal(), 'Security Audit Log'),
+      h('div', { style: _cardTitleStyle }, I.journal(), 'Security Audit Log', h(HelpButton, { label: 'Security Audit Log' },
+        h('p', null, 'Controls what security events are logged for this agent. Enable comprehensive logging for high-risk agents, or keep minimal logging for routine agents to reduce storage.')
+      )),
       h('p', { style: _cardDescStyle }, 'Agent-specific security logging settings'),
       h(GlobalToggle, { section: 'auditSecurity', label: 'Security Audit Log' }),
       !useGlobal.auditSecurity && (function() {

package/dist/dashboard/pages/agent-detail/skills-section.js

@@ -2,6 +2,7 @@ import { h, useState, useEffect, useCallback, Fragment, useApp, apiCall, engineC
 import { I } from '../../components/icons.js';
 import { E } from '../../assets/icons/emoji-icons.js';
 import { Badge, EmptyState } from './shared.js?v=4';
+import { HelpButton } from '../../components/help-button.js';
 
 // ════════════════════════════════════════════════════════════
 // SKILLS SECTION — View and manage agent skills
@@ -127,7 +128,14 @@ export function SkillsSection(props) {
   // View mode
   return h(Fragment, null,
     h('div', { style: { display: 'flex', justifyContent: 'space-between', alignItems: 'center', marginBottom: 20 } },
-      h('h3', { style: { margin: 0, fontSize: 16, fontWeight: 600 } }, 'Skills & Capabilities'),
+      h('h3', { style: { margin: 0, fontSize: 16, fontWeight: 600, display: 'flex', alignItems: 'center' } }, 'Skills & Capabilities', h(HelpButton, { label: 'Skills & Capabilities' },
+        h('p', null, 'Skills are packages of tools and capabilities that an agent can use. Each skill unlocks specific functionality like email management, web browsing, or calendar access.'),
+        h('ul', { style: { paddingLeft: 20, margin: '4px 0 8px' } },
+          h('li', null, h('strong', null, 'Suites'), ' — Pre-built bundles of related skills (e.g., Google Workspace suite includes Gmail, Calendar, Drive).'),
+          h('li', null, h('strong', null, 'Individual Skills'), ' — Toggle specific capabilities on or off for fine-grained control.')
+        ),
+        h('div', { style: { marginTop: 12, padding: 12, background: 'var(--bg-secondary, #1e293b)', borderRadius: 'var(--radius, 8px)', fontSize: 13 } }, h('strong', null, 'Tip: '), 'Start with a suite, then remove individual skills you don\'t need. Changes apply immediately if the agent is running (hot-update).')
+      )),
       h('div', { style: { display: 'flex', gap: 8, alignItems: 'center' } },
         h('span', { className: 'badge badge-primary' }, currentSkills.length + ' skills'),
         h('button', { className: 'btn btn-primary btn-sm', onClick: startEdit }, I.journal(), ' Edit Skills')

package/dist/dashboard/pages/agent-detail/tool-security.js

@@ -3,6 +3,7 @@ import { I } from '../../components/icons.js';
 import { E } from '../../assets/icons/emoji-icons.js';
 import { TagInput } from '../../components/tag-input.js';
 import { Badge, EmptyState } from './shared.js?v=4';
+import { HelpButton } from '../../components/help-button.js';
 
 var _tsCardStyle = { border: '1px solid var(--border)', borderRadius: 'var(--radius)', padding: 20, marginBottom: 16 };
 var _tsCardTitle = { fontSize: 15, fontWeight: 600, marginBottom: 4, display: 'flex', alignItems: 'center', gap: 8 };
@@ -232,7 +233,17 @@ export function ToolSecuritySection(props) {
     // Header
     h('div', { style: { display: 'flex', justifyContent: 'space-between', alignItems: 'center', marginBottom: 20 } },
       h('div', null,
-        h('h3', { style: { margin: 0, fontSize: 18, fontWeight: 600 } }, 'Tool Security'),
+        h('h3', { style: { margin: 0, fontSize: 18, fontWeight: 600, display: 'flex', alignItems: 'center' } }, 'Tool Security', h(HelpButton, { label: 'Tool Security' },
+          h('p', null, 'Configure security sandboxes and middleware for this agent\'s tool usage. Unmodified settings inherit from organization defaults.'),
+          h('ul', { style: { paddingLeft: 20, margin: '4px 0 8px' } },
+            h('li', null, h('strong', null, 'Path Sandbox'), ' — Restricts which directories the agent can read/write.'),
+            h('li', null, h('strong', null, 'SSRF Protection'), ' — Blocks access to internal networks and metadata endpoints.'),
+            h('li', null, h('strong', null, 'Command Sanitizer'), ' — Controls which shell commands are allowed.'),
+            h('li', null, h('strong', null, 'Rate Limiting'), ' — Per-tool call limits to prevent runaway behavior.'),
+            h('li', null, h('strong', null, 'Circuit Breaker'), ' — Auto-stops calling failing tools after repeated errors.')
+          ),
+          h('div', { style: { marginTop: 12, padding: 12, background: 'var(--bg-secondary, #1e293b)', borderRadius: 'var(--radius, 8px)', fontSize: 13 } }, h('strong', null, 'Tip: '), 'Only override settings you need to change. Agent-level overrides take precedence over org defaults. Use "Reset to Org Defaults" to remove all overrides.')
+        )),
         h('p', { style: { margin: '4px 0 0', fontSize: 13, color: 'var(--text-muted)' } },
           'Configure tool security overrides for this agent. Unmodified settings inherit from ',
           h('strong', null, 'org defaults'),
@@ -273,7 +284,10 @@ export function ToolSecuritySection(props) {
 
       // Path Sandbox
       h('div', { style: _tsCardStyle },
-        h('div', { style: _tsCardTitle }, I.folder(), ' Path Sandbox'),
+        h('div', { style: _tsCardTitle }, I.folder(), ' Path Sandbox', h(HelpButton, { label: 'Path Sandbox' },
+          h('p', null, 'Restricts file system access to specific directories. Prevents agents from reading sensitive files like .env, SSH keys, or system configs.'),
+          h('div', { style: { marginTop: 12, padding: 12, background: 'var(--bg-secondary, #1e293b)', borderRadius: 'var(--radius, 8px)', fontSize: 13 } }, h('strong', null, 'Tip: '), 'Add your project directory to allowed dirs. Use blocked patterns to exclude sensitive files like .env or credentials.')
+        )),
         h('div', { style: _tsCardDesc }, 'Controls which directories this agent can read/write.'),
         h(TSToggle, { label: 'Enable path sandboxing', checked: ps.enabled !== false, inherited: !isOverridden('pathSandbox', 'enabled'), onChange: function(v) { patchSec('pathSandbox', 'enabled', v); } }),
         h(TagInput, { label: 'Allowed Directories', value: ps.allowedDirs || [], onChange: function(v) { patchSec('pathSandbox', 'allowedDirs', v); }, placeholder: '/path/to/allow', mono: true }),
@@ -282,7 +296,9 @@ export function ToolSecuritySection(props) {
 
       // SSRF Guard
       h('div', { style: _tsCardStyle },
-        h('div', { style: _tsCardTitle }, I.globe(), ' SSRF Protection'),
+        h('div', { style: _tsCardTitle }, I.globe(), ' SSRF Protection', h(HelpButton, { label: 'SSRF Protection' },
+          h('p', null, 'Server-Side Request Forgery protection prevents the agent from accessing internal infrastructure like cloud metadata endpoints (169.254.x.x), private networks (10.x.x.x), or localhost services.')
+        )),
         h('div', { style: _tsCardDesc }, 'Blocks this agent from accessing internal networks and metadata endpoints.'),
         h(TSToggle, { label: 'Enable SSRF protection', checked: ssrf.enabled !== false, inherited: !isOverridden('ssrf', 'enabled'), onChange: function(v) { patchSec('ssrf', 'enabled', v); } }),
         h(TagInput, { label: 'Allowed Hosts', value: ssrf.allowedHosts || [], onChange: function(v) { patchSec('ssrf', 'allowedHosts', v); }, placeholder: 'api.example.com', mono: true }),
@@ -292,7 +308,10 @@ export function ToolSecuritySection(props) {
 
     // Command Sanitizer (full width)
     h('div', { style: _tsCardStyle },
-      h('div', { style: _tsCardTitle }, I.terminal(), ' Command Sanitizer'),
+      h('div', { style: _tsCardTitle }, I.terminal(), ' Command Sanitizer', h(HelpButton, { label: 'Command Sanitizer' },
+        h('p', null, 'Controls shell command execution. Use blocklist mode to deny dangerous commands, or allowlist mode to only permit specific safe commands.'),
+        h('div', { style: { marginTop: 12, padding: 12, background: 'var(--bg-secondary, #1e293b)', borderRadius: 'var(--radius, 8px)', fontSize: 13 } }, h('strong', null, 'Tip: '), 'Allowlist mode is more secure but requires listing every allowed command. Blocklist mode is easier — just block dangerous patterns like "rm -rf" or "curl | sh".')
+      )),
       h('div', { style: _tsCardDesc }, 'Controls which shell commands this agent can execute.'),
       h(TSToggle, { label: 'Enable command validation', checked: cs.enabled !== false, inherited: !isOverridden('commandSanitizer', 'enabled'), onChange: function(v) { patchSec('commandSanitizer', 'enabled', v); } }),
       h('div', { style: { marginBottom: 12 } },
@@ -314,7 +333,9 @@ export function ToolSecuritySection(props) {
 
       // Audit Logging
       h('div', { style: _tsCardStyle },
-        h('div', { style: _tsCardTitle }, I.journal(), ' Audit Logging'),
+        h('div', { style: _tsCardTitle }, I.journal(), ' Audit Logging', h(HelpButton, { label: 'Audit Logging' },
+          h('p', null, 'Records every tool call this agent makes. Essential for compliance, debugging, and understanding agent behavior. Sensitive values are automatically redacted.')
+        )),
         h('div', { style: _tsCardDesc }, 'Logs every tool invocation for this agent.'),
         h(TSToggle, { label: 'Enable audit logging', checked: audit.enabled !== false, inherited: !isOverridden('audit', 'enabled'), onChange: function(v) { patchMw('audit', 'enabled', v); } }),
         h(TagInput, { label: 'Keys to Redact', value: audit.redactKeys || [], onChange: function(v) { patchMw('audit', 'redactKeys', v); }, placeholder: 'custom_secret', mono: true })
@@ -322,7 +343,9 @@ export function ToolSecuritySection(props) {
 
       // Rate Limiting
       h('div', { style: _tsCardStyle },
-        h('div', { style: _tsCardTitle }, I.clock(), ' Rate Limiting'),
+        h('div', { style: _tsCardTitle }, I.clock(), ' Rate Limiting', h(HelpButton, { label: 'Rate Limiting' },
+          h('p', null, 'Sets maximum calls per minute for each tool. Prevents runaway loops where the agent calls the same tool hundreds of times. Each tool has a token bucket that refills at the configured rate.')
+        )),
         h('div', { style: _tsCardDesc }, 'Per-tool rate limits for this agent.'),
         h(TSToggle, { label: 'Enable rate limiting', checked: rl.enabled !== false, inherited: !isOverridden('rateLimit', 'enabled'), onChange: function(v) { patchMw('rateLimit', 'enabled', v); } }),
         h(TSRateLimitEditor, { overrides: rl.overrides || {}, onChange: function(v) { patchMw('rateLimit', 'overrides', v); } })
@@ -330,14 +353,18 @@ export function ToolSecuritySection(props) {
 
       // Circuit Breaker
       h('div', { style: _tsCardStyle },
-        h('div', { style: _tsCardTitle }, I.pause(), ' Circuit Breaker'),
+        h('div', { style: _tsCardTitle }, I.pause(), ' Circuit Breaker', h(HelpButton, { label: 'Circuit Breaker' },
+          h('p', null, 'Automatically stops calling a tool after consecutive failures. Prevents wasting tokens and API calls on broken integrations. The circuit "opens" after failures and "closes" after a cooldown period.')
+        )),
         h('div', { style: _tsCardDesc }, 'Auto-stops calling failing tools after consecutive failures.'),
         h(TSToggle, { label: 'Enable circuit breaker', checked: cb.enabled !== false, inherited: !isOverridden('circuitBreaker', 'enabled'), onChange: function(v) { patchMw('circuitBreaker', 'enabled', v); } })
       ),
 
       // Telemetry
       h('div', { style: _tsCardStyle },
-        h('div', { style: _tsCardTitle }, I.chart(), ' Telemetry'),
+        h('div', { style: _tsCardTitle }, I.chart(), ' Telemetry', h(HelpButton, { label: 'Telemetry' },
+          h('p', null, 'Collects timing data, success rates, and usage patterns for this agent\'s tools. Useful for identifying slow tools, optimizing workflows, and capacity planning.')
+        )),
         h('div', { style: _tsCardDesc }, 'Collects execution timing and metrics for this agent\'s tools.'),
         h(TSToggle, { label: 'Enable telemetry', checked: tel.enabled !== false, inherited: !isOverridden('telemetry', 'enabled'), onChange: function(v) { patchMw('telemetry', 'enabled', v); } })
       )