@agenticmail/enterprise 0.5.198 → 0.5.200

package/dist/dashboard/pages/settings.js

@@ -231,7 +231,11 @@ export function SettingsPage() {
 
     tab === 'general' && h('div', null,
       h('div', { className: 'card', style: { marginBottom: 16 } },
-        h('div', { className: 'card-header' }, h('h3', null, 'Organization')),
+        h('div', { className: 'card-header' }, h('h3', { style: { display: 'flex', alignItems: 'center' } }, 'Organization', h(HelpButton, { label: 'Organization Settings' },
+          h('p', null, 'Core settings for your AgenticMail Enterprise instance — company name, domain, branding, and plan tier.'),
+          h('p', null, h('strong', null, 'Plan: '), 'Self-hosted installations have no restrictions. Set a plan tier to enforce agent limits if needed.'),
+          h('p', { style: { marginTop: 8, padding: 8, background: 'var(--bg-secondary, #1e293b)', borderRadius: 6, fontSize: 13 } }, h('strong', null, 'Tip: '), 'Your brand color and logo are used throughout the dashboard and in agent-facing UIs.')
+        ))),
         h('div', { className: 'card-body' },
           h('div', { style: { display: 'grid', gridTemplateColumns: '1fr 1fr', gap: 16 } },
             h('div', { className: 'form-group' },
@@ -278,7 +282,10 @@ export function SettingsPage() {
       // ─── Email Signature Template ─────────────────────
       h('div', { className: 'card' },
         h('div', { className: 'card-header' },
-          h('h3', null, 'Email Signature Template'),
+          h('h3', { style: { display: 'flex', alignItems: 'center' } }, 'Email Signature Template', h(HelpButton, { label: 'Email Signature Template' },
+            h('p', null, 'Define a shared HTML signature that all agents use in their outgoing emails. Use template variables like {{name}}, {{role}}, {{email}} to personalize per agent.'),
+            h('p', { style: { marginTop: 8, padding: 8, background: 'var(--bg-secondary, #1e293b)', borderRadius: 6, fontSize: 13 } }, h('strong', null, 'Tip: '), 'Test your signature by previewing it below the editor. The preview uses sample data to show how it will look.')
+          )),
           h('span', { style: { fontSize: 12, color: 'var(--text-muted)', marginLeft: 8 } }, 'Applied to all agents')
         ),
         h('div', { className: 'card-body' },
@@ -331,7 +338,11 @@ export function SettingsPage() {
 
       h('div', { className: 'card' },
         h('div', { className: 'card-header' },
-          h('h3', null, 'Organization Email'),
+          h('h3', { style: { display: 'flex', alignItems: 'center' } }, 'Organization Email', h(HelpButton, { label: 'Organization Email' },
+            h('p', null, 'Set up a shared OAuth application (Google or Microsoft) that all agents use for email access. Each agent still authorizes individually, but they share the same Client ID and Secret.'),
+            h('p', null, h('strong', null, 'Why: '), 'Without this, each agent would need its own OAuth app registration. This centralizes the setup.'),
+            h('p', { style: { marginTop: 8, padding: 8, background: 'var(--bg-secondary, #1e293b)', borderRadius: 6, fontSize: 13 } }, h('strong', null, 'Tip: '), 'Follow the setup instructions carefully — you\'ll need to create an OAuth app in the provider\'s developer console and add the correct redirect URI.')
+          )),
           orgEmail.configured && h('span', { className: 'badge badge-success', style: { marginLeft: 8 } }, orgEmail.label || 'Configured')
         ),
         h('div', { className: 'card-body' },
@@ -515,7 +526,12 @@ export function SettingsPage() {
     tab === 'authentication' && h('div', null,
       h(TwoFactorCard, { toast: toast }),
       h('div', { className: 'card', style: { marginBottom: 16 } },
-        h('div', { className: 'card-header' }, h('h3', null, 'Single Sign-On (SSO)')),
+        h('div', { className: 'card-header' }, h('h3', { style: { display: 'flex', alignItems: 'center' } }, 'Single Sign-On (SSO)', h(HelpButton, { label: 'Single Sign-On (SSO)' },
+          h('p', null, 'Let your team sign into AgenticMail using their existing corporate identity provider (Okta, Google Workspace, Azure AD, etc.).'),
+          h('p', null, h('strong', null, 'SAML 2.0'), ' — Enterprise standard, works with Okta, OneLogin, Azure AD.'),
+          h('p', null, h('strong', null, 'OIDC'), ' — Modern alternative, works with Google, Microsoft, Auth0.'),
+          h('p', { style: { marginTop: 8, padding: 8, background: 'var(--bg-secondary, #1e293b)', borderRadius: 6, fontSize: 13 } }, h('strong', null, 'Tip: '), 'Use the Quick Setup section below to pre-fill provider discovery URLs. You still need to create an OAuth app in the provider\'s console.')
+        ))),
         h('div', { className: 'card-body' },
           h('p', { style: { color: 'var(--text-secondary)', fontSize: 13, marginBottom: 16 } }, 'Configure SAML 2.0 or OIDC to let team members sign in with their corporate identity provider.'),
           h('div', { style: { display: 'grid', gridTemplateColumns: '1fr 1fr', gap: 16 } },
@@ -626,7 +642,12 @@ export function SettingsPage() {
         )
       ),
       h('div', { className: 'card' },
-        h('div', { className: 'card-header' }, h('h3', null, 'Email & Domain Configuration')),
+        h('div', { className: 'card-header' }, h('h3', { style: { display: 'flex', alignItems: 'center' } }, 'Email & Domain Configuration', h(HelpButton, { label: 'Email & Domain Configuration' },
+          h('p', null, 'Configure how your agents send and receive email. Choose between a simple Gmail/Outlook relay or a professional custom domain setup.'),
+          h('p', null, h('strong', null, 'Relay'), ' — Easy, agents send from yourname+agent@gmail.com. Great for getting started.'),
+          h('p', null, h('strong', null, 'Custom Domain'), ' — Professional, agents send from agent@yourdomain.com with DKIM/SPF/DMARC.'),
+          h('p', { style: { marginTop: 8, padding: 8, background: 'var(--bg-secondary, #1e293b)', borderRadius: 6, fontSize: 13 } }, h('strong', null, 'Tip: '), 'Start with relay for quick setup. Upgrade to a custom domain when you need professional email branding.')
+        ))),
         h('div', { className: 'card-body' },
           h('p', { style: { color: 'var(--text-secondary)', fontSize: 13, marginBottom: 20 } }, 'Configure how agents send and receive email. Choose between a relay (Gmail/Outlook forwarding) or a custom domain with full DKIM/SPF/DMARC.'),
           h('div', { style: { display: 'grid', gridTemplateColumns: '1fr 1fr', gap: 16 } },
@@ -670,7 +691,10 @@ export function SettingsPage() {
       h('div', { className: 'card', style: { marginBottom: 16 } },
         h('div', { className: 'card-header' },
           h('div', { style: { display: 'flex', justifyContent: 'space-between', alignItems: 'center' } },
-            h('h3', null, 'Deploy Credentials'),
+            h('h3', { style: { display: 'flex', alignItems: 'center' } }, 'Deploy Credentials', h(HelpButton, { label: 'Deploy Credentials' },
+              h('p', null, 'Store credentials for deploying agents to external platforms (Docker registries, cloud providers, etc.). These are encrypted at rest with AES-256-GCM.'),
+              h('p', { style: { marginTop: 8, padding: 8, background: 'var(--bg-secondary, #1e293b)', borderRadius: 6, fontSize: 13 } }, h('strong', null, 'Tip: '), 'Add credentials here before using the agent deployment feature. Each credential is tied to a specific target type (Docker, Kubernetes, etc.).')
+            )),
             h('button', { className: 'btn btn-primary btn-sm', onClick: () => { setDeployForm({ name: '', targetType: 'docker', config: {} }); setShowDeployModal(true); } }, I.plus(), ' Add Credential')
           )
         ),

package/dist/dashboard/pages/skill-connections.js

@@ -1,6 +1,7 @@
 import { h, useState, useEffect, useCallback, Fragment, useApp, engineCall } from '../components/utils.js';
 import { I } from '../components/icons.js';
 import { Modal } from '../components/modal.js';
+import { HelpButton } from '../components/help-button.js';
 
 // Auth help: where to get API keys/tokens for each skill
 var AUTH_HELP = {
@@ -334,11 +335,24 @@ export function SkillConnectionsPage() {
     );
   }
 
+  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,
     // Page Header
     h('div', { style: { display: 'flex', justifyContent: 'space-between', alignItems: 'center', marginBottom: 20 } },
       h('div', null,
-        h('h1', { style: { fontSize: 20, fontWeight: 700 } }, 'Skill Connections'),
+        h('h1', { style: { fontSize: 20, fontWeight: 700, display: 'flex', alignItems: 'center' } }, 'Skill Connections', h(HelpButton, { label: 'Skill Connections' },
+          h('p', null, 'Manage the authentication and configuration for your installed community skills. Each skill needs to be connected to its external service before agents can use it.'),
+          h('h4', { style: _h4 }, 'Connection Types'),
+          h('ul', { style: _ul },
+            h('li', null, h('strong', null, 'OAuth'), ' — Secure token-based auth. Click "Connect" to authorize via the service\'s login page.'),
+            h('li', null, h('strong', null, 'API Key / Token'), ' — Paste credentials from the service\'s developer portal.'),
+            h('li', null, h('strong', null, 'Configure'), ' — Set custom options like default channels, project IDs, or behavior tweaks.')
+          ),
+          h('div', { style: _tip }, h('strong', null, 'Tip: '), 'Look for the "How to connect" box on each skill card — it links directly to where you get credentials.')
+        )),
         h('p', { style: { color: 'var(--text-muted)', fontSize: 13 } }, 'Connect external services and configure skill settings')
       ),
       h('button', { className: 'btn btn-secondary', onClick: load }, I.refresh(), ' Refresh')
@@ -347,15 +361,15 @@ export function SkillConnectionsPage() {
     // Stats Bar
     h('div', { className: 'stat-grid', style: { marginBottom: 20 } },
       h('div', { className: 'stat-card' },
-        h('div', { className: 'stat-label' }, 'Total Installed'),
+        h('div', { className: 'stat-label', style: { display: 'flex', alignItems: 'center' } }, 'Total Installed', h(HelpButton, { label: 'Total Installed' }, h('p', null, 'The number of community skills you\'ve installed from the marketplace. These are available to connect and use with your agents.'))),
         h('div', { className: 'stat-value' }, totalInstalled)
       ),
       h('div', { className: 'stat-card' },
-        h('div', { className: 'stat-label' }, 'Connected'),
+        h('div', { className: 'stat-label', style: { display: 'flex', alignItems: 'center' } }, 'Connected', h(HelpButton, { label: 'Connected' }, h('p', null, 'Skills that have been successfully authenticated with their external service. Connected skills are ready for agents to use.'))),
         h('div', { className: 'stat-value', style: { color: 'var(--success)' } }, connectedCount)
       ),
       h('div', { className: 'stat-card' },
-        h('div', { className: 'stat-label' }, 'Needs Configuration'),
+        h('div', { className: 'stat-label', style: { display: 'flex', alignItems: 'center' } }, 'Needs Configuration', h(HelpButton, { label: 'Needs Configuration' }, h('p', null, 'Skills that are installed but not yet connected. They need API keys, OAuth authorization, or other credentials before agents can use them.'))),
         h('div', { className: 'stat-value', style: { color: needsConfigCount > 0 ? 'var(--warning)' : 'var(--text-muted)' } }, needsConfigCount)
       )
     ),

package/dist/dashboard/pages/skills.js

@@ -1,6 +1,7 @@
 import { h, useState, useEffect, useCallback, Fragment, useApp, engineCall, getOrgId } from '../components/utils.js';
 import { I } from '../components/icons.js';
 import { Modal } from '../components/modal.js';
+import { HelpButton } from '../components/help-button.js';
 
 export function SkillsPage() {
   var app = useApp();
@@ -551,7 +552,16 @@ export function SkillsPage() {
     // Header with stats
     h('div', { style: { display: 'flex', justifyContent: 'space-between', alignItems: 'center', marginBottom: 20 } },
       h('div', null,
-        h('h1', { style: { fontSize: 20, fontWeight: 700 } }, 'Skills & Integrations'),
+        h('h1', { style: { fontSize: 20, fontWeight: 700, display: 'flex', alignItems: 'center' } }, 'Skills & Integrations', h(HelpButton, { label: 'Skills & Integrations' },
+          h('p', null, 'Skills give your agents the ability to interact with external services. Integrations connect to third-party platforms like Slack, GitHub, Jira, and more.'),
+          h('h4', { style: { marginTop: 16, marginBottom: 8, fontSize: 14 } }, 'Tabs'),
+          h('ul', { style: { paddingLeft: 20, margin: '4px 0 8px' } },
+            h('li', null, h('strong', null, 'Integrations'), ' — Connect external services (OAuth, API keys, credentials). Connected services give agents real tools.'),
+            h('li', null, h('strong', null, 'Builtin Skills'), ' — Pre-packaged capabilities that come with the platform. Always available.'),
+            h('li', null, h('strong', null, 'Installed'), ' — Community skills you\'ve installed from the marketplace. Manage connections and configuration here.')
+          ),
+          h('div', { style: { marginTop: 12, padding: 12, background: 'var(--bg-secondary, #1e293b)', borderRadius: 8, fontSize: 13 } }, h('strong', null, 'Tip: '), 'Start with Integrations tab — connect the services your agents need, and they\'ll automatically get access to the relevant tools.')
+        )),
         h('p', { style: { color: 'var(--text-muted)', fontSize: 13 } },
           allSkills.length + ' builtin \u00B7 ' + integrations.length + ' integrations \u00B7 ' + intConnectedCount + ' connected'
         )

package/dist/dashboard/pages/users.js

@@ -1,6 +1,7 @@
 import { h, useState, useEffect, Fragment, useApp, apiCall, showConfirm } from '../components/utils.js';
 import { I } from '../components/icons.js';
 import { Modal } from '../components/modal.js';
+import { HelpButton } from '../components/help-button.js';
 
 export function UsersPage() {
   var { toast } = useApp();
@@ -58,7 +59,19 @@ export function UsersPage() {
 
   return h(Fragment, null,
     h('div', { style: { display: 'flex', justifyContent: 'space-between', alignItems: 'center', marginBottom: 20 } },
-      h('div', null, h('h1', { style: { fontSize: 20, fontWeight: 700 } }, 'Users'), h('p', { style: { color: 'var(--text-muted)', fontSize: 13 } }, 'Manage team members and their access')),
+      h('div', null, h('h1', { style: { fontSize: 20, fontWeight: 700, display: 'flex', alignItems: 'center' } }, 'Users', h(HelpButton, { label: 'Users' },
+        h('p', null, 'Manage dashboard users who can access and administer the AgenticMail Enterprise console. Each user has a role that controls what they can see and do.'),
+        h('h4', { style: { marginTop: 16, marginBottom: 8, fontSize: 14 } }, 'Roles'),
+        h('ul', { style: { paddingLeft: 20, margin: '4px 0 8px' } },
+          h('li', null, h('strong', null, 'Owner'), ' — Full access including billing, user management, and destructive actions.'),
+          h('li', null, h('strong', null, 'Admin'), ' — Can manage agents, policies, and most settings. Cannot manage billing.'),
+          h('li', null, h('strong', null, 'Member'), ' — Can view dashboards and interact with agents. Limited config access.'),
+          h('li', null, h('strong', null, 'Viewer'), ' — Read-only access to dashboards and reports.')
+        ),
+        h('h4', { style: { marginTop: 16, marginBottom: 8, fontSize: 14 } }, '2FA (Two-Factor Authentication)'),
+        h('p', null, 'Users can enable TOTP-based 2FA for extra security. The 2FA column shows whether it\'s active.'),
+        h('div', { style: { marginTop: 12, padding: 12, background: 'var(--bg-secondary, #1e293b)', borderRadius: 'var(--radius, 8px)', fontSize: 13 } }, h('strong', null, 'Tip: '), 'Use the lock icon to reset a user\'s password. The "Generate" button creates a secure random password.')
+      )), h('p', { style: { color: 'var(--text-muted)', fontSize: 13 } }, 'Manage team members and their access')),
       h('button', { className: 'btn btn-primary', onClick: function() { setCreating(true); } }, I.plus(), ' Add User')
     ),
 

package/dist/dashboard/pages/vault.js

@@ -1,6 +1,7 @@
 import { h, useState, useEffect, useCallback, Fragment, useApp, engineCall, getOrgId } from '../components/utils.js';
 import { I } from '../components/icons.js';
 import { Modal } from '../components/modal.js';
+import { HelpButton } from '../components/help-button.js';
 
 var PAGE_SIZE = 25;
 
@@ -522,7 +523,16 @@ export function VaultPage() {
 
       h('div', { className: 'card' },
         h('div', { className: 'card-header' },
-          h('h3', { style: { fontSize: 14, fontWeight: 600 } }, 'Secrets by Category')
+          h('h3', { style: { fontSize: 14, fontWeight: 600, display: 'flex', alignItems: 'center' } }, 'Secrets by Category', h(HelpButton, { label: 'Secrets by Category' },
+            h('p', null, 'Breakdown of stored secrets by their category. Helps you understand what types of credentials are in your vault.'),
+            h('ul', { style: { paddingLeft: 20, margin: '4px 0 8px' } },
+              h('li', null, h('strong', null, 'Deploy Credentials'), ' — Infrastructure and deployment secrets.'),
+              h('li', null, h('strong', null, 'Skill Credentials'), ' — API keys for agent tools (OpenAI, Slack, etc).'),
+              h('li', null, h('strong', null, 'Cloud Storage'), ' — AWS, GCP, and other cloud provider keys.'),
+              h('li', null, h('strong', null, 'API Keys'), ' — General-purpose API keys.'),
+              h('li', null, h('strong', null, 'Custom'), ' — User-defined secrets.')
+            )
+          ))
         ),
         h('div', { className: 'card-body' },
           Object.keys(byCategory).length === 0
@@ -563,7 +573,17 @@ export function VaultPage() {
   return h(Fragment, null,
     h('div', { style: { display: 'flex', justifyContent: 'space-between', alignItems: 'center', marginBottom: 20 } },
       h('div', null,
-        h('h1', { style: { fontSize: 20, fontWeight: 700 } }, 'Vault'),
+        h('h1', { style: { fontSize: 20, fontWeight: 700, display: 'flex', alignItems: 'center' } }, 'Vault', h(HelpButton, { label: 'Vault' },
+          h('p', null, 'Securely store and manage API keys, passwords, and credentials used by your agents. All secrets are encrypted at rest with AES-256-GCM.'),
+          h('h4', { style: { marginTop: 16, marginBottom: 8, fontSize: 14 } }, 'Key features'),
+          h('ul', { style: { paddingLeft: 20, margin: '4px 0 8px' } },
+            h('li', null, h('strong', null, 'Platform presets'), ' — Quick setup for OpenAI, Anthropic, GitHub, Stripe, and more.'),
+            h('li', null, h('strong', null, 'Key rotation'), ' — Re-encrypt secrets with fresh keys without changing the value.'),
+            h('li', null, h('strong', null, 'Full audit trail'), ' — Every read, create, delete, and rotate is logged.'),
+            h('li', null, h('strong', null, 'Auto-detection'), ' — Secrets stored as skill:<platform>:<key> are auto-detected by agent tools.')
+          ),
+          h('div', { style: { marginTop: 12, padding: 12, background: 'var(--bg-secondary, #1e293b)', borderRadius: 'var(--radius, 8px)', fontSize: 13 } }, h('strong', null, 'Tip: '), 'Rotate secrets periodically. Use "Rotate All" for bulk re-encryption after a security incident.')
+        )),
         h('p', { style: { color: 'var(--text-muted)', fontSize: 13 } }, 'Encrypted secrets management with AES-256-GCM')
       ),
       h('button', { className: 'btn btn-secondary', onClick: function() { loadSecrets(); loadStatus(); if (tab === 'audit') loadAudit(); } }, I.refresh(), ' Refresh')

package/dist/dashboard/pages/workforce.js

@@ -1,6 +1,7 @@
 import { h, useState, useEffect, useCallback, Fragment, useApp, engineCall, buildAgentEmailMap, resolveAgentEmail, buildAgentDataMap, renderAgentBadge, getOrgId } from '../components/utils.js';
 import { I } from '../components/icons.js';
 import { TimezoneSelect } from '../components/timezones.js';
+import { HelpButton } from '../components/help-button.js';
 
 export function WorkforcePage() {
   const { toast } = useApp();
@@ -245,9 +246,24 @@ export function WorkforcePage() {
     { key: 'history', label: 'Clock History' },
   ];
 
+  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('div', { className: 'page-inner' },
     h('div', { className: 'page-header' },
-      h('h1', null, 'Workforce Management'),
+      h('h1', { style: { display: 'flex', alignItems: 'center' } }, 'Workforce Management', h(HelpButton, { label: 'Workforce Management' },
+        h('p', null, 'Manage your agents like employees — set work schedules, assign tasks, track budgets, and monitor clock-in/out history.'),
+        h('h4', { style: _h4 }, 'Key sections'),
+        h('ul', { style: _ul },
+          h('li', null, h('strong', null, 'Overview'), ' — See which agents are clocked in, off duty, or unscheduled.'),
+          h('li', null, h('strong', null, 'Schedules'), ' — Define working hours, shifts, and auto-wake rules.'),
+          h('li', null, h('strong', null, 'Task Queue'), ' — Assign and track tasks for specific agents.'),
+          h('li', null, h('strong', null, 'Budgets'), ' — Set token caps to control agent spending.'),
+          h('li', null, h('strong', null, 'Clock History'), ' — Audit trail of all clock-in/out events.')
+        ),
+        h('div', { style: _tip }, h('strong', null, 'Tip: '), 'Use schedules with auto-wake to have agents automatically start working at their scheduled time each day.')
+      )),
       h('button', { className: 'btn btn-ghost', onClick: loadData }, I.refresh(), ' Refresh')
     ),
     // Tab bar

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agenticmail/enterprise",
-  "version": "0.5.198",
+  "version": "0.5.200",
   "description": "AgenticMail Enterprise — cloud-hosted AI agent identity, email, auth & compliance for organizations",
   "type": "module",
   "bin": {

package/src/dashboard/HELP-TOOLTIPS-GUIDE.md

@@ -0,0 +1,45 @@
+# Help Tooltips Implementation Guide
+
+## Pattern
+Use the existing `HelpButton` component from `../components/help-button.js` (or `../../components/help-button.js` for agent-detail).
+
+### Import
+```js
+import { HelpButton } from '../components/help-button.js';
+```
+
+### Usage
+Add HelpButton next to section titles, card headers, stat labels, and tab headers:
+```js
+h('h3', { style: { display: 'flex', alignItems: 'center' } }, 
+  'Section Title',
+  h(HelpButton, { label: 'Section Title' },
+    h('p', null, 'Main explanation of what this section does.'),
+    h('h4', { style: _h4 }, 'Key Concepts'),
+    h('ul', { style: _ul },
+      h('li', null, 'Concept 1 explanation'),
+      h('li', null, 'Concept 2 explanation'),
+    ),
+    h('div', { style: _tip }, h('strong', null, 'Tip: '), 'Helpful tip here.')
+  )
+)
+```
+
+### Style Variables (define at top of render function)
+```js
+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 };
+```
+
+## Rules
+1. Add HelpButton to EVERY card header, section title, and stat label
+2. Keep help text concise but useful — explain what it is, why it matters, and how to use it
+3. Include "Tip:" boxes for actionable advice
+4. Use h4 for sub-headings within help modals
+5. Use ul/li for lists of concepts
+6. Don't repeat obvious UI labels — explain the WHY
+7. Reference the existing knowledge-contributions.js page for the gold standard example
+8. Make sure to import HelpButton at the top of each file
+9. DO NOT change any existing functionality — only ADD help tooltips
+10. Test that the file is valid JS after changes (no syntax errors)

package/src/dashboard/pages/activity.js

@@ -1,5 +1,6 @@
 import { h, useState, useEffect, useCallback, Fragment, engineCall, buildAgentDataMap, renderAgentBadge, getOrgId } from '../components/utils.js';
 import { DetailModal } from '../components/modal.js';
+import { HelpButton } from '../components/help-button.js';
 
 const PAGE_SIZE = 25;
 
@@ -85,9 +86,21 @@ export function ActivityPage() {
   const eventsPages = Math.ceil(eventsTotal / PAGE_SIZE);
   const toolsPages = Math.ceil(toolsTotal / PAGE_SIZE);
 
+  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,
     h('div', { style: { marginBottom: 20 } },
-      h('h1', { style: { fontSize: 20, fontWeight: 700 } }, 'Activity'),
+      h('h1', { style: { fontSize: 20, fontWeight: 700, display: 'flex', alignItems: 'center' } }, 'Activity', h(HelpButton, { label: 'Activity' },
+        h('p', null, 'A real-time feed of everything your agents are doing — events they generate and tools they call.'),
+        h('h4', { style: _h4 }, 'Two views'),
+        h('ul', { style: _ul },
+          h('li', null, h('strong', null, 'Events'), ' — High-level actions: agent started, stopped, deployed, errored, etc.'),
+          h('li', null, h('strong', null, 'Tool Calls'), ' — Granular tool usage: which tool, duration, success/failure, parameters and results.')
+        ),
+        h('div', { style: _tip }, h('strong', null, 'Tip: '), 'Use the agent and type filters to zero in on specific behavior. Click any row to see full details.')
+      )),
       h('p', { style: { color: 'var(--text-muted)', fontSize: 13 } }, 'Real-time activity and tool usage across all agents')
     ),
 

package/src/dashboard/pages/agent-detail/activity.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 { DetailModal } from '../../components/modal.js';
+import { HelpButton } from '../../components/help-button.js';
 
 // --- ActivitySection ------------------------------------------------
 
@@ -136,7 +137,22 @@ export function ActivitySection(props) {
 
   return h('div', { className: 'card' },
     h('div', { className: 'card-header', style: { display: 'flex', alignItems: 'center', justifyContent: 'space-between' } },
-      h('h3', { style: { margin: 0, fontSize: 15, fontWeight: 600 } }, 'Activity'),
+      h('h3', { style: { margin: 0, fontSize: 15, fontWeight: 600, display: 'flex', alignItems: 'center' } }, 'Activity',
+        h(HelpButton, { label: 'Agent Activity Log' },
+          h('p', null, 'A chronological log of everything this agent has done — conversations, tasks completed, emails sent, tools used, errors encountered, and guardrail interventions.'),
+          h('h4', { style: { marginTop: 16, marginBottom: 8, fontSize: 14 } }, 'Event Types'),
+          h('ul', { style: { paddingLeft: 20, margin: '4px 0 8px' } },
+            h('li', null, h('strong', null, 'Message'), ' — Chat messages sent or received.'),
+            h('li', null, h('strong', null, 'Task'), ' — Tasks started, completed, or failed.'),
+            h('li', null, h('strong', null, 'Tool Use'), ' — External tools or APIs the agent called.'),
+            h('li', null, h('strong', null, 'Error'), ' — Failures, timeouts, or API errors.'),
+            h('li', null, h('strong', null, 'Guardrail'), ' — Policy violations or interventions.'),
+            h('li', null, h('strong', null, 'System'), ' — Deploy, restart, config changes.')
+          ),
+          h('p', null, 'Click on any event to see full details including request/response data.'),
+          h('div', { style: { marginTop: 12, padding: 12, background: 'var(--bg-secondary, #1e293b)', borderRadius: 'var(--radius, 8px)', fontSize: 13 } }, h('strong', null, 'Tip: '), 'Use filters to narrow down to specific event types. If debugging an issue, start with "Error" events.')
+        )
+      ),
       h('div', { style: { display: 'flex', gap: 8, alignItems: 'center' } },
         h('span', { style: { fontSize: 11, color: 'var(--text-muted)' } }, filtered.length + ' items'),
         h('button', { className: 'btn btn-ghost btn-sm', onClick: refreshCurrent }, I.refresh())

package/src/dashboard/pages/agent-detail/autonomy.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';
 
 // ════════════════════════════════════════════════════════════
 // AGENT DETAIL PAGE  (Main Orchestrator)
@@ -118,7 +119,22 @@ export function AutonomySection(props) {
     // Header
     h('div', { style: { display: 'flex', justifyContent: 'space-between', alignItems: 'center', marginBottom: 16 } },
       h('div', null,
-        h('div', { style: { fontSize: 15, fontWeight: 600 } }, 'Agent Autonomy Settings'),
+        h('div', { style: { fontSize: 15, fontWeight: 600, display: 'flex', alignItems: 'center' } }, 'Agent Autonomy Settings',
+          h(HelpButton, { label: 'Autonomy Settings' },
+            h('p', null, 'Autonomy settings control what the agent does automatically without being asked. Think of it as the agent\'s daily routine.'),
+            h('h4', { style: { marginTop: 16, marginBottom: 8, fontSize: 14 } }, 'Automated Behaviors'),
+            h('ul', { style: { paddingLeft: 20, margin: '4px 0 8px' } },
+              h('li', null, h('strong', null, 'Auto Clock-In/Out'), ' — Agent automatically starts and stops work based on its schedule in the Workforce tab.'),
+              h('li', null, h('strong', null, 'Daily Catch-up'), ' — At a set time each day, the agent reviews unread emails, messages, and pending tasks to stay on top of things.'),
+              h('li', null, h('strong', null, 'Weekly Catch-up'), ' — A deeper weekly review that may include summaries, reports, or planning.'),
+              h('li', null, h('strong', null, 'Goal Check'), ' — Periodic check-ins against assigned goals/OKRs.'),
+              h('li', null, h('strong', null, 'Knowledge Contributions'), ' — Agent periodically contributes learnings to the organization\'s knowledge base.'),
+              h('li', null, h('strong', null, 'Escalation'), ' — Automatically escalates issues it can\'t handle to its manager.'),
+              h('li', null, h('strong', null, 'Guardrail Enforcement'), ' — Self-monitors for compliance with organizational policies.')
+            ),
+            h('div', { style: { marginTop: 12, padding: 12, background: 'var(--bg-secondary, #1e293b)', borderRadius: 'var(--radius, 8px)', fontSize: 13 } }, h('strong', null, 'Tip: '), 'Start with daily catch-up enabled and add more behaviors as the agent proves reliable. The master switch lets you disable all autonomy instantly.')
+          )
+        ),
         h('div', { style: { fontSize: 12, color: 'var(--text-muted)' } }, 'Configure automated behaviors — all times use agent timezone')
       ),
       h('div', { style: { display: 'flex', gap: 8 } },

package/src/dashboard/pages/agent-detail/budget.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 { StatCard, ProgressBar, formatNumber, formatCost } from './shared.js?v=4';
+import { HelpButton } from '../../components/help-button.js';
 
 // ════════════════════════════════════════════════════════════
 // BUDGET SECTION
@@ -117,7 +118,19 @@ export function BudgetSection(props) {
     // ─── Budget Limits Card ─────────────────────────────
     h('div', { className: 'card', style: { marginBottom: 20 } },
       h('div', { className: 'card-header', style: { display: 'flex', justifyContent: 'space-between', alignItems: 'center' } },
-        h('span', null, 'Budget Limits'),
+        h('span', { style: { display: 'flex', alignItems: 'center' } }, 'Budget Limits',
+          h(HelpButton, { label: 'Budget Limits' },
+            h('p', null, 'Set spending caps to prevent this agent from exceeding your API budget. When a limit is reached, the agent is automatically paused.'),
+            h('h4', { style: { marginTop: 16, marginBottom: 8, fontSize: 14 } }, 'Limit Types'),
+            h('ul', { style: { paddingLeft: 20, margin: '4px 0 8px' } },
+              h('li', null, h('strong', null, 'Daily Limit'), ' — Maximum spend per day (resets at midnight UTC). Prevents runaway costs from a single day\'s usage.'),
+              h('li', null, h('strong', null, 'Monthly Limit'), ' — Maximum spend per calendar month. Your overall budget control.'),
+              h('li', null, h('strong', null, 'Per-Request Limit'), ' — Maximum cost for a single API call. Prevents accidentally using expensive models or very long prompts.')
+            ),
+            h('p', null, 'Set to 0 or leave blank for no limit. The progress bars show current usage against each limit.'),
+            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 conservative daily limit, monitor usage for a week, then adjust. It\'s easier to raise limits than to deal with a surprise $500 bill.')
+          )
+        ),
         !editing && h('button', { className: 'btn btn-secondary btn-sm', onClick: function() { setEditing(true); } }, 'Edit Budget')
       ),
       h('div', { className: 'card-body' },
@@ -177,7 +190,17 @@ export function BudgetSection(props) {
 
     // ─── Budget Alerts Table ────────────────────────────
     h('div', { className: 'card', style: { marginBottom: 20 } },
-      h('div', { className: 'card-header' }, h('span', null, 'Budget Alerts')),
+      h('div', { className: 'card-header' }, h('span', { style: { display: 'flex', alignItems: 'center' } }, 'Budget Alerts',
+        h(HelpButton, { label: 'Budget Alerts' },
+          h('p', null, 'Get notified when the agent approaches or exceeds budget thresholds.'),
+          h('ul', { style: { paddingLeft: 20, margin: '4px 0 8px' } },
+            h('li', null, h('strong', null, 'Warning'), ' — Sent when usage reaches a percentage of the limit (e.g., 80%). Agent continues running.'),
+            h('li', null, h('strong', null, 'Critical'), ' — Sent when usage is very close to the limit (e.g., 95%). Consider pausing non-essential tasks.'),
+            h('li', null, h('strong', null, 'Exceeded'), ' — The limit was hit and the agent was automatically paused. Requires manual resume or limit increase.')
+          ),
+          h('div', { style: { marginTop: 12, padding: 12, background: 'var(--bg-secondary, #1e293b)', borderRadius: 'var(--radius, 8px)', fontSize: 13 } }, h('strong', null, 'Tip: '), 'Alerts are sent to the agent\'s manager (if configured) and to the admin email.')
+        )
+      )),
       budgetAlerts.length > 0
         ? h('div', { className: 'card-body-flush' },
             h('table', { className: 'data-table' },

package/src/dashboard/pages/agent-detail/channels.js

@@ -1,6 +1,7 @@
 import { h, useState, useEffect, useCallback, Fragment, useApp, apiCall, engineCall, getOrgId } from '../../components/utils.js';
 import { I } from '../../components/icons.js';
 import { E } from '../../assets/icons/emoji-icons.js';
+import { HelpButton } from '../../components/help-button.js';
 
 // ─── Styles ───
 
@@ -449,7 +450,15 @@ export function ChannelsSection(props) {
   var noChannels = !caps?.whatsapp && !caps?.telegram;
 
   return h('div', null,
-    h('h2', { style: { fontSize: '20px', marginBottom: '16px' } }, 'Manager Messaging Channels'),
+    h('h2', { style: { fontSize: '20px', marginBottom: '16px', display: 'flex', alignItems: 'center' } }, 'Manager Messaging Channels', h(HelpButton, { label: 'Manager Messaging Channels' },
+      h('p', null, 'Connect personal messaging platforms so you can chat with your AI agent directly from WhatsApp or Telegram. These are your private channels — for customer-facing messaging, use the WhatsApp Business tab.'),
+      h('ul', { style: { paddingLeft: 20, margin: '4px 0 8px' } },
+        h('li', null, h('strong', null, 'Manager Identity'), ' — Set your phone number/user ID so the agent recognizes you across platforms.'),
+        h('li', null, h('strong', null, 'WhatsApp'), ' — Link via QR code. Uses your personal WhatsApp as a linked device.'),
+        h('li', null, h('strong', null, 'Telegram'), ' — Create a bot via @BotFather and paste the token.')
+      ),
+      h('div', { style: { marginTop: 12, padding: 12, background: 'var(--bg-secondary, #1e293b)', borderRadius: 'var(--radius, 8px)', fontSize: 13 } }, h('strong', null, 'Tip: '), 'Add trusted contacts to control who can message the agent. Only trusted contacts get responses — everyone else gets an auto-reply.')
+    )),
 
     noChannels && h('div', { style: Object.assign({}, cardStyle, { textAlign: 'center', padding: '40px' }) },
       h('div', { style: { marginBottom: '12px' } }, E.chat(40)),

package/src/dashboard/pages/agent-detail/communication.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';
 
 // --- CommunicationSection -------------------------------------------
 
@@ -126,7 +127,15 @@ export function CommunicationSection(props) {
 
   return h('div', { className: 'card' },
     h('div', { className: 'card-header', style: { display: 'flex', alignItems: 'center', justifyContent: 'space-between' } },
-      h('h3', { style: { margin: 0, fontSize: 15, fontWeight: 600 } }, 'Communication'),
+      h('h3', { style: { margin: 0, fontSize: 15, fontWeight: 600, display: 'flex', alignItems: 'center' } }, 'Communication', h(HelpButton, { label: 'Communication' },
+        h('p', null, 'Inter-agent messaging system. Agents can send messages to each other for coordination, task delegation, and information sharing.'),
+        h('ul', { style: { paddingLeft: 20, margin: '4px 0 8px' } },
+          h('li', null, h('strong', null, 'All Messages'), ' — Complete message history (sent and received).'),
+          h('li', null, h('strong', null, 'Inbox'), ' — Unread messages waiting for this agent. Mark as read after review.'),
+          h('li', null, h('strong', null, 'Topology'), ' — Visual map of which agents communicate with each other and how frequently.')
+        ),
+        h('div', { style: { marginTop: 12, padding: 12, background: 'var(--bg-secondary, #1e293b)', borderRadius: 'var(--radius, 8px)', fontSize: 13 } }, h('strong', null, 'Tip: '), 'Use priority levels (urgent, high, normal, low) to help agents triage incoming messages.')
+      )),
       h('div', { style: { display: 'flex', gap: 8 } },
         h('button', { className: 'btn btn-primary btn-sm', onClick: function() { setShowSend(true); } }, I.plus(), ' Send Message'),
         h('button', { className: 'btn btn-ghost btn-sm', onClick: refreshCurrent }, I.refresh(), ' Refresh')