@agenticmail/enterprise 0.5.199 → 0.5.200

package/dist/dashboard/pages/domain-status.js

@@ -1,6 +1,7 @@
 import { h, useState, useEffect, useCallback, Fragment, useApp, apiCall, showConfirm } 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';
 
 export function DomainStatusPage() {
   var { toast } = useApp();
@@ -165,6 +166,9 @@ export function DomainStatusPage() {
   var sub = data && data.subdomain;
 
   // ─── 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 };
   var card = { padding: 24, background: 'var(--bg-secondary)', borderRadius: 'var(--radius-lg)', border: '1px solid var(--border)', marginBottom: 16 };
   var labelSt = { fontSize: 11, fontWeight: 700, color: 'var(--text-muted)', textTransform: 'uppercase', letterSpacing: 0.8, marginBottom: 10 };
   var rowSt = { display: 'flex', justifyContent: 'space-between', alignItems: 'center', padding: '10px 0', borderBottom: '1px solid var(--border)' };
@@ -172,7 +176,18 @@ export function DomainStatusPage() {
   return h(Fragment, null,
     // ─── Page Header ──────────────────────────────
     h('div', { style: { marginBottom: 24 } },
-      h('h1', { style: { fontSize: 20, fontWeight: 700 } }, 'Domain & Deployment'),
+      h('h1', { style: { fontSize: 20, fontWeight: 700, display: 'flex', alignItems: 'center' } }, 'Domain & Deployment', h(HelpButton, { label: 'Domain & Deployment' },
+        h('p', null, 'Configure how your AgenticMail Enterprise instance is accessed on the internet. Set up subdomains, custom domains, CORS policies, and deployment tunnels.'),
+        h('h4', { style: _h4 }, 'Sections'),
+        h('ul', { style: _ul },
+          h('li', null, h('strong', null, 'Current Deployment'), ' — The URL where your dashboard is running right now.'),
+          h('li', null, h('strong', null, 'Subdomain'), ' — Your free agenticmail.io subdomain.'),
+          h('li', null, h('strong', null, 'Custom Domain'), ' — Use your own domain with DNS verification.'),
+          h('li', null, h('strong', null, 'CORS'), ' — Control which origins can make API requests.'),
+          h('li', null, h('strong', null, 'Migration'), ' — Move your deployment to another machine.')
+        ),
+        h('div', { style: _tip }, h('strong', null, 'Tip: '), 'If running locally, use the "Deploy to Production" section to expose your instance via a Cloudflare Tunnel.')
+      )),
       h('p', { style: { color: 'var(--text-muted)', fontSize: 13 } }, 'Manage the domain and URL for your AgenticMail Enterprise deployment')
     ),
 
@@ -185,7 +200,10 @@ export function DomainStatusPage() {
     // SECTION 1: Current Deployment
     // ═══════════════════════════════════════════════
     h('div', { style: card },
-      h('div', { style: labelSt }, 'Current Deployment'),
+      h('div', { style: Object.assign({}, labelSt, { display: 'flex', alignItems: 'center' }) }, 'Current Deployment', h(HelpButton, { label: 'Current Deployment' },
+        h('p', null, 'This shows the URL you\'re currently accessing the dashboard from. This is where your team and agents connect.'),
+        h('div', { style: _tip }, h('strong', null, 'Tip: '), 'Share this URL with your team. If it shows localhost, you\'ll need to set up a tunnel or deploy to a server for external access.')
+      )),
       h('div', { style: { padding: '14px 16px', background: 'var(--bg-primary)', borderRadius: 'var(--radius)', display: 'flex', alignItems: 'center', justifyContent: 'space-between', border: '1px solid var(--border)', marginBottom: 12 } },
         h('span', { style: { fontSize: 15, fontFamily: 'var(--font-mono, monospace)', color: 'var(--accent)', wordBreak: 'break-all' } }, actualUrl),
         h('button', { className: 'btn btn-sm', onClick: function() { navigator.clipboard.writeText(actualUrl); toast('Copied!', 'success'); } }, 'Copy')
@@ -200,7 +218,10 @@ export function DomainStatusPage() {
     // ═══════════════════════════════════════════════
     h('div', { style: card },
       h('div', { style: { display: 'flex', alignItems: 'center', justifyContent: 'space-between', marginBottom: 12 } },
-        h('div', { style: labelSt }, 'AgenticMail Subdomain'),
+        h('div', { style: Object.assign({}, labelSt, { display: 'flex', alignItems: 'center' }) }, 'AgenticMail Subdomain', h(HelpButton, { label: 'AgenticMail Subdomain' },
+          h('p', null, 'A free subdomain on agenticmail.io (e.g., yourcompany.agenticmail.io). This gives you a public URL without needing your own domain.'),
+          h('div', { style: _tip }, h('strong', null, 'Tip: '), 'Changing the subdomain requires updating DNS records and any bookmarks or integrations that reference the old URL.')
+        )),
         !showEditSub && sub && h('button', { className: 'btn btn-sm', onClick: function() { setShowEditSub(true); setNewSub(sub || ''); setSubError(''); } }, 'Change')
       ),
 
@@ -268,7 +289,16 @@ export function DomainStatusPage() {
     h('div', { style: card },
       h('div', { style: { display: 'flex', alignItems: 'center', justifyContent: 'space-between', marginBottom: 16 } },
         h('div', null,
-          h('div', { style: labelSt }, 'Custom Domain'),
+          h('div', { style: Object.assign({}, labelSt, { display: 'flex', alignItems: 'center' }) }, 'Custom Domain', h(HelpButton, { label: 'Custom Domain' },
+            h('p', null, 'Use your own domain (e.g., agents.yourcompany.com) for a professional, branded deployment. Requires DNS verification to prove ownership.'),
+            h('h4', { style: _h4 }, 'Setup Process'),
+            h('ul', { style: _ul },
+              h('li', null, h('strong', null, 'Register'), ' — Enter your domain and get DNS challenge records.'),
+              h('li', null, h('strong', null, 'Add DNS records'), ' — Add TXT (verification) and CNAME/A (routing) records at your DNS provider.'),
+              h('li', null, h('strong', null, 'Verify'), ' — Click "Verify DNS Now" once records propagate (up to 48 hours).')
+            ),
+            h('div', { style: _tip }, h('strong', null, 'Tip: '), 'Use a subdomain like agents.yourcompany.com instead of the root domain — it\'s easier to set up and doesn\'t affect your main website.')
+          )),
           h('div', { style: { fontSize: 12, color: 'var(--text-muted)', marginTop: -6 } }, 'Deploy on your own domain — either a subdomain (agents.yourcompany.com) or root domain (yourcompany.com)')
         )
       ),
@@ -399,7 +429,15 @@ export function DomainStatusPage() {
     // ═══════════════════════════════════════════════
     h('div', { style: card },
       h('div', { style: { display: 'flex', alignItems: 'center', justifyContent: 'space-between', marginBottom: 12 } },
-        h('div', { style: labelSt }, 'Allowed Origins (CORS)'),
+        h('div', { style: Object.assign({}, labelSt, { display: 'flex', alignItems: 'center' }) }, 'Allowed Origins (CORS)', h(HelpButton, { label: 'Allowed Origins (CORS)' },
+          h('p', null, 'CORS (Cross-Origin Resource Sharing) controls which websites can make API requests to your AgenticMail server. This is a security measure to prevent unauthorized access.'),
+          h('h4', { style: _h4 }, 'What This Means'),
+          h('ul', { style: _ul },
+            h('li', null, h('strong', null, 'No origins listed'), ' — Any website can make API requests (open access). Fine for development, risky for production.'),
+            h('li', null, h('strong', null, 'Origins listed'), ' — Only those specific domains can make API requests.')
+          ),
+          h('div', { style: _tip }, h('strong', null, 'Tip: '), 'CORS is auto-updated when you change your subdomain or custom domain. For manual control, go to Settings → Network & Firewall.')
+        )),
         h('a', { href: '/dashboard/settings#network', style: { fontSize: 12, color: 'var(--accent)', textDecoration: 'none', fontWeight: 500 } }, 'Manage in Settings \u2192')
       ),
       corsOrigins.length === 0
@@ -424,7 +462,10 @@ export function DomainStatusPage() {
       h('div', { style: { display: 'flex', alignItems: 'center', gap: 10, marginBottom: 12 } },
         h('span', { style: { fontSize: 20 } }, '\uD83D\uDCE6'),
         h('div', null,
-          h('div', { style: { fontSize: 14, fontWeight: 700 } }, 'Migrate to Another Machine'),
+          h('div', { style: { fontSize: 14, fontWeight: 700, display: 'flex', alignItems: 'center' } }, 'Migrate to Another Machine', h(HelpButton, { label: 'Migration' },
+            h('p', null, 'Move your entire AgenticMail deployment to a different server or computer. All you need is the .env file — it contains all configuration and encryption keys.'),
+            h('div', { style: _tip }, h('strong', null, 'Tip: '), 'Always back up your .env file securely. Without the VAULT_KEY, encrypted credentials cannot be recovered.')
+          )),
           h('div', { style: { fontSize: 12, color: 'var(--text-muted)' } }, 'Move your entire deployment to a new server or computer')
         )
       ),
@@ -467,7 +508,10 @@ export function DomainStatusPage() {
     // CLI Reference
     // ═══════════════════════════════════════════════
     h('div', { style: card },
-      h('div', { style: labelSt }, 'CLI Commands'),
+      h('div', { style: Object.assign({}, labelSt, { display: 'flex', alignItems: 'center' }) }, 'CLI Commands', h(HelpButton, { label: 'CLI Commands' },
+        h('p', null, 'Common command-line commands for managing your AgenticMail Enterprise installation. Run these in your terminal on the server where AgenticMail is installed.'),
+        h('div', { style: _tip }, h('strong', null, 'Tip: '), 'Use "npx @agenticmail/enterprise@latest" to always run the latest version without manually updating.')
+      )),
       h('div', { style: { display: 'grid', gap: 8 } },
         cliRow('Initial setup', 'npx @agenticmail/enterprise setup'),
         cliRow('Start server', 'npx @agenticmail/enterprise start'),

package/dist/dashboard/pages/guardrails.js

@@ -1,5 +1,6 @@
 import { h, useState, useEffect, useCallback, Fragment, useApp, engineCall, buildAgentEmailMap, resolveAgentEmail, buildAgentDataMap, renderAgentBadge, getOrgId } from '../components/utils.js';
 import { I } from '../components/icons.js';
+import { HelpButton } from '../components/help-button.js';
 
 // ─── Constants ──────────────────────────────────────────
 
@@ -111,8 +112,23 @@ export function GuardrailsPage() {
     { id: 'rules', label: 'Rules & Interventions' },
   ];
 
+  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, 'Guardrails & Intervention')),
+    h('div', { className: 'page-header' }, h('h1', { style: { display: 'flex', alignItems: 'center' } }, 'Guardrails & Intervention', h(HelpButton, { label: 'Guardrails & Intervention' },
+      h('p', null, 'Central control panel for agent safety. Define policies agents must follow, configure automated rules that trigger interventions, manage onboarding, and inspect agent memory.'),
+      h('h4', { style: _h4 }, 'Tabs overview'),
+      h('ul', { style: _ul },
+        h('li', null, h('strong', null, 'Overview'), ' — Quick stats, agent controls (pause/resume/kill), onboarding status, and recent interventions.'),
+        h('li', null, h('strong', null, 'Policies'), ' — Define behavioral rules agents must acknowledge and follow.'),
+        h('li', null, h('strong', null, 'Onboarding'), ' — Track which agents have acknowledged org policies.'),
+        h('li', null, h('strong', null, 'Agent Memory'), ' — View and manage what agents remember.'),
+        h('li', null, h('strong', null, 'Rules & Interventions'), ' — Automated guardrail rules, anomaly detection, and intervention history.')
+      ),
+      h('div', { style: _tip }, h('strong', null, 'Tip: '), 'Start with the Overview tab for a quick health check, then drill into specific tabs for detailed management.')
+    ))),
     h('div', { className: 'tabs', style: { marginBottom: 16 } },
       TABS.map(function(t) { return h('button', { key: t.id, className: 'tab' + (activeTab === t.id ? ' active' : ''), onClick: function() { setTab(t.id); } }, t.label); })
     ),
@@ -208,7 +224,14 @@ function OverviewTab(props) {
     ),
     // Onboarding progress summary
     onboardingData.length > 0 && h('div', { className: 'card', style: { marginBottom: 16 } },
-      h('div', { className: 'card-header' }, h('h3', null, 'Agent Onboarding Status')),
+      h('div', { className: 'card-header' }, h('h3', { style: { display: 'flex', alignItems: 'center' } }, 'Agent Onboarding Status', h(HelpButton, { label: 'Agent Onboarding Status' },
+        h('p', null, 'Shows which agents have acknowledged your organization\'s policies. Agents must complete onboarding before they can operate fully.'),
+        h('ul', { style: { paddingLeft: 20, margin: '4px 0 8px' } },
+          h('li', null, h('strong', null, 'Green'), ' — Completed all required policy acknowledgments.'),
+          h('li', null, h('strong', null, 'Yellow'), ' — In progress, some policies still pending.'),
+          h('li', null, h('strong', null, 'Red'), ' — Needs renewal due to policy changes.')
+        )
+      ))),
       h('div', { className: 'card-body' },
         onboardingData.slice(0, 8).map(function(ag) {
           var statusColor = ag.overallStatus === 'completed' ? '#10b981' : ag.overallStatus === 'in_progress' ? '#f59e0b' : ag.overallStatus === 'needs_renewal' ? '#ef4444' : '#64748b';
@@ -223,7 +246,10 @@ function OverviewTab(props) {
     ),
     // Recent interventions
     h('div', { className: 'card' },
-      h('div', { className: 'card-header' }, h('h3', null, 'Recent Interventions')),
+      h('div', { className: 'card-header' }, h('h3', { style: { display: 'flex', alignItems: 'center' } }, 'Recent Interventions', h(HelpButton, { label: 'Recent Interventions' },
+        h('p', null, 'Log of recent agent interventions — pauses, kills, and resumes. Shows what happened, which agent was affected, and who triggered it.'),
+        h('div', { style: { marginTop: 12, padding: 12, background: 'var(--bg-secondary, #1e293b)', borderRadius: 'var(--radius, 8px)', fontSize: 13 } }, h('strong', null, 'Tip: '), 'If an agent was paused by an automated rule, you can resume it directly from the Actions column.')
+      ))),
       interventions.length === 0
         ? h(EmptyState, { message: 'No interventions recorded' })
         : h('table', { className: 'data-table' },

package/dist/dashboard/pages/journal.js

@@ -1,5 +1,6 @@
 import { h, useState, useEffect, Fragment, useApp, engineCall, buildAgentEmailMap, buildAgentDataMap, resolveAgentEmail, renderAgentBadge, getOrgId } from '../components/utils.js';
 import { I } from '../components/icons.js';
+import { HelpButton } from '../components/help-button.js';
 
 export function JournalPage() {
   const { toast } = useApp();
@@ -23,12 +24,31 @@ export function JournalPage() {
     try { const r = await engineCall('/journal/' + id + '/rollback', { method: 'POST', body: JSON.stringify({}) }); if (r.success) { toast('Action rolled back', 'success'); load(); } else toast('Rollback failed: ' + (r.error || 'Unknown'), 'error'); } catch (e) { toast(e.message, 'error'); }
   };
 
+  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, 'Action Journal')),
+    h('div', { className: 'page-header' }, h('h1', { style: { display: 'flex', alignItems: 'center' } }, 'Action Journal', h(HelpButton, { label: 'Action Journal' },
+      h('p', null, 'A tamper-proof log of every action agents have taken. Think of it as an audit trail — every tool call, every side effect, recorded with full context.'),
+      h('h4', { style: _h4 }, 'Why it matters'),
+      h('ul', { style: _ul },
+        h('li', null, h('strong', null, 'Accountability'), ' — Know exactly what each agent did and when.'),
+        h('li', null, h('strong', null, 'Rollback'), ' — Reverse actions that were mistakes or caused issues.'),
+        h('li', null, h('strong', null, 'Compliance'), ' — Maintain a full audit trail for regulatory needs.')
+      ),
+      h('div', { style: _tip }, h('strong', null, 'Tip: '), 'Use the Rollback button on reversible actions to undo agent mistakes without manual intervention.')
+    ))),
     stats && h('div', { className: 'stat-grid', style: { marginBottom: 16 } },
-      h('div', { className: 'stat-card' }, h('div', { className: 'stat-value' }, stats.total), h('div', { className: 'stat-label' }, 'Total Actions')),
-      h('div', { className: 'stat-card' }, h('div', { className: 'stat-value' }, stats.reversible), h('div', { className: 'stat-label' }, 'Reversible')),
-      h('div', { className: 'stat-card' }, h('div', { className: 'stat-value' }, stats.reversed), h('div', { className: 'stat-label' }, 'Rolled Back'))
+      h('div', { className: 'stat-card' }, h('div', { className: 'stat-value' }, stats.total), h('div', { className: 'stat-label', style: { display: 'flex', alignItems: 'center' } }, 'Total Actions', h(HelpButton, { label: 'Total Actions' },
+        h('p', null, 'The total number of tool calls and side effects recorded across all agents.')
+      ))),
+      h('div', { className: 'stat-card' }, h('div', { className: 'stat-value' }, stats.reversible), h('div', { className: 'stat-label', style: { display: 'flex', alignItems: 'center' } }, 'Reversible', h(HelpButton, { label: 'Reversible' },
+        h('p', null, 'Actions that can be undone (rolled back). Not all actions are reversible — for example, sent emails cannot be unsent.')
+      ))),
+      h('div', { className: 'stat-card' }, h('div', { className: 'stat-value' }, stats.reversed), h('div', { className: 'stat-label', style: { display: 'flex', alignItems: 'center' } }, 'Rolled Back', h(HelpButton, { label: 'Rolled Back' },
+        h('p', null, 'Actions that have been reversed by an admin. A high number may indicate agents need tighter permissions or better instructions.')
+      )))
     ),
     h('div', { className: 'card' },
       h('table', { className: 'data-table' },

package/dist/dashboard/pages/knowledge-contributions.js

@@ -267,7 +267,19 @@ export function KnowledgeContributionsPage() {
 
     return h(Fragment, null,
       h('div', { style: { display: 'flex', justifyContent: 'space-between', alignItems: 'center', marginBottom: 16 } },
-        h('span', { style: { fontSize: 13, color: 'var(--text-muted)' } }, bases.length + ' knowledge base' + (bases.length !== 1 ? 's' : '')),
+        h('span', { style: { fontSize: 13, color: 'var(--text-muted)', display: 'flex', alignItems: 'center' } }, bases.length + ' knowledge base' + (bases.length !== 1 ? 's' : ''),
+          h(HelpButton, { label: 'Knowledge Bases' },
+            h('p', null, 'Each knowledge base is a searchable collection of documents. Agents use these to answer questions with real organizational data instead of guessing.'),
+            h('h4', { style: _h4 }, 'How It Works'),
+            h('ul', { style: _ul },
+              h('li', null, h('strong', null, 'Create'), ' a knowledge base and give it a descriptive name (e.g., "HR Policies", "Product Docs").'),
+              h('li', null, h('strong', null, 'Import'), ' documents via the Knowledge Import page — upload files, crawl URLs, or paste text.'),
+              h('li', null, h('strong', null, 'Assign'), ' the knowledge base to agents in their Deployment tab.'),
+              h('li', null, h('strong', null, 'Search'), ' happens automatically when agents use the knowledge_base_search tool.')
+            ),
+            h('div', { style: _tip }, h('strong', null, 'Tip: '), 'Click on a knowledge base to see its documents and chunks. Chunks are the small pieces of text that get matched during search — smaller chunks give more precise results.')
+          )
+        ),
         h('button', { className: 'btn btn-primary', onClick: function() { setShowCreateBase(true); } }, I.plus(), ' Create Knowledge Base')
       ),
       bases.length === 0
@@ -425,6 +437,21 @@ export function KnowledgeContributionsPage() {
   var agentData = buildAgentDataMap(agents);
 
   var renderContributions = function() {
+    // Header with help
+    var _contribHeader = h('div', { style: { display: 'flex', alignItems: 'center', gap: 4, marginBottom: 12 } },
+      h('span', { style: { fontSize: 14, fontWeight: 600 } }, 'Agent Contributions'),
+      h(HelpButton, { label: 'Agent Contributions' },
+        h('p', null, 'Every entry here is a piece of knowledge an agent contributed — a fact learned, a decision recorded, a process documented, or an insight captured during work.'),
+        h('h4', { style: _h4 }, 'Contribution Details'),
+        h('ul', { style: _ul },
+          h('li', null, h('strong', null, 'Confidence'), ' — How certain the agent is about this knowledge (0-100%). Higher confidence = more reliable. Contributions below your threshold are flagged for review.'),
+          h('li', null, h('strong', null, 'Category'), ' — The type of knowledge (fact, process, decision, preference, etc.). Helps organize and filter.'),
+          h('li', null, h('strong', null, 'Source'), ' — Where the agent learned this (conversation, email, document, etc.).')
+        ),
+        h('div', { style: _tip }, h('strong', null, 'Tip: '), 'Review low-confidence contributions periodically. You can edit, approve, or delete them. High-quality contributions improve all agents that share this knowledge base.')
+      )
+    );
+
     // Filter
     var filtered = contributions;
     if (contribAgent) filtered = filtered.filter(function(c) { return c.agentId === contribAgent; });
@@ -440,6 +467,7 @@ export function KnowledgeContributionsPage() {
     var paged = filtered.slice(contribPage * CONTRIB_PAGE_SIZE, (contribPage + 1) * CONTRIB_PAGE_SIZE);
 
     return h(Fragment, null,
+      _contribHeader,
       // Filter bar
       h('div', { style: { display: 'flex', gap: 10, marginBottom: 14, flexWrap: 'wrap', alignItems: 'center' } },
         h('input', {
@@ -506,7 +534,18 @@ export function KnowledgeContributionsPage() {
   var renderSchedules = function() {
     return h(Fragment, null,
       h('div', { style: { display: 'flex', justifyContent: 'space-between', alignItems: 'center', marginBottom: 16 } },
-        h('span', { style: { fontSize: 13, color: 'var(--text-muted)' } }, schedules.length + ' schedule' + (schedules.length !== 1 ? 's' : '')),
+        h('span', { style: { fontSize: 13, color: 'var(--text-muted)', display: 'flex', alignItems: 'center' } }, schedules.length + ' schedule' + (schedules.length !== 1 ? 's' : ''),
+          h(HelpButton, { label: 'Contribution Schedules' },
+            h('p', null, 'Schedules automate knowledge contributions. Instead of relying on agents to contribute spontaneously, schedules trigger periodic knowledge synthesis.'),
+            h('h4', { style: _h4 }, 'How Schedules Work'),
+            h('ul', { style: _ul },
+              h('li', null, 'Pick an agent and a target knowledge base.'),
+              h('li', null, 'Set the frequency (hourly, daily, weekly, monthly) and a minimum confidence threshold.'),
+              h('li', null, 'At each interval, the agent reviews its recent memories and contributes relevant knowledge above the confidence threshold.')
+            ),
+            h('div', { style: _tip }, h('strong', null, 'Tip: '), 'Weekly schedules with 60%+ confidence work well for most use cases. Daily schedules generate more granular but potentially noisier contributions.')
+          )
+        ),
         h('button', { className: 'btn btn-primary', onClick: function() { setShowCreateSchedule(true); } }, I.plus(), ' Create Schedule')
       ),
       schedules.length === 0
@@ -1183,6 +1222,20 @@ export function KnowledgeContributionsPage() {
     var m = searchMetrics;
 
     return h('div', null,
+      h('div', { style: { display: 'flex', alignItems: 'center', gap: 4, marginBottom: 16 } },
+        h('span', { style: { fontSize: 14, fontWeight: 600 } }, 'Search Metrics'),
+        h(HelpButton, { label: 'Search Metrics' },
+          h('p', null, 'Track how agents are searching your knowledge bases. This helps you understand which bases are useful and where there are gaps.'),
+          h('h4', { style: _h4 }, 'Key Metrics'),
+          h('ul', { style: _ul },
+            h('li', null, h('strong', null, 'Total Searches'), ' — How many times agents searched knowledge bases in the selected period.'),
+            h('li', null, h('strong', null, 'KB vs Hub Searches'), ' — KB searches target a specific knowledge base; Hub searches query across all bases.'),
+            h('li', null, h('strong', null, 'Hit Rate'), ' — Percentage of searches that returned useful results. Low hit rates mean agents are searching for things not in your knowledge bases.'),
+            h('li', null, h('strong', null, 'Avg Results'), ' — Average number of results per search. Too few = gaps in content; too many = content may be too broad.')
+          ),
+          h('div', { style: _tip }, h('strong', null, 'Tip: '), 'If hit rate is low, check the "Top Queries with No Results" section to see what\'s missing from your knowledge bases, then import relevant content.')
+        )
+      ),
       // Filters
       h('div', { style: { display: 'flex', gap: 12, marginBottom: 20 } },
         h('select', {
@@ -1325,7 +1378,20 @@ export function KnowledgeContributionsPage() {
     // Header
     h('div', { style: { display: 'flex', justifyContent: 'space-between', alignItems: 'center', marginBottom: 20 } },
       h('div', null,
-        h('h1', { style: { fontSize: 20, fontWeight: 700 } }, 'Knowledge Contributions'),
+        h('h1', { style: { fontSize: 20, fontWeight: 700, display: 'flex', alignItems: 'center' } }, 'Knowledge Contributions',
+          h(HelpButton, { label: 'Knowledge Contributions' },
+            h('p', null, 'This is where your agents build shared organizational knowledge. Agents contribute what they learn from conversations, tasks, and research into knowledge bases that all agents can search.'),
+            h('h4', { style: _h4 }, 'Tabs'),
+            h('ul', { style: _ul },
+              h('li', null, h('strong', null, 'Knowledge Bases'), ' — Create and manage knowledge bases. Each is a collection of documents that agents can search via RAG (Retrieval-Augmented Generation).'),
+              h('li', null, h('strong', null, 'Contributions'), ' — Browse individual knowledge entries that agents have contributed. Filter by agent, search by content, and review quality.'),
+              h('li', null, h('strong', null, 'Schedules'), ' — Automate knowledge contributions on a schedule (e.g., weekly synthesis of learnings).'),
+              h('li', null, h('strong', null, 'Stats'), ' — Charts showing contribution volume, confidence levels, category distribution, and agent quality over time.'),
+              h('li', null, h('strong', null, 'Search Metrics'), ' — How agents are using knowledge search — query volume, hit rates, and which bases are most useful.')
+            ),
+            h('div', { style: _tip }, h('strong', null, 'Tip: '), 'Start by creating a knowledge base, then enable knowledge contributions in each agent\'s Autonomy settings. Agents will automatically contribute what they learn.')
+          )
+        ),
         h('p', { style: { color: 'var(--text-muted)', fontSize: 13 } },
           'Collaborative knowledge building from agent memories and experiences'
         )

package/dist/dashboard/pages/knowledge-import.js

@@ -12,6 +12,7 @@ import { h, useState, useEffect, useRef, Fragment, useApp, engineCall, getOrgId
 import { I } from '../components/icons.js';
 import { ProviderLogo } from '../assets/provider-logos.js';
 import { Modal } from '../components/modal.js';
+import { HelpButton } from '../components/help-button.js';
 
 // ─── Platform Definitions ────────────────────────────
 
@@ -421,7 +422,11 @@ export function ImportJobsList({ kbId }) {
 
   return h('div', { className: 'card', style: { marginTop: 16 } },
     h('div', { className: 'card-header' },
-      h('h3', { style: { margin: 0, fontSize: 14 } }, 'Import History'),
+      h('h3', { style: { margin: 0, fontSize: 14, display: 'flex', alignItems: 'center' } }, 'Import History', h(HelpButton, { label: 'Import History' },
+        h('p', null, 'Shows all previous import jobs for this knowledge base. Track the status, source, and results of each import.'),
+        h('p', null, h('strong', null, 'Statuses: '), 'completed (all documents imported), running (in progress), failed (error occurred), cancelled (manually stopped).'),
+        h('p', { style: { marginTop: 8, padding: 8, background: 'var(--bg-secondary, #1e293b)', borderRadius: 6, fontSize: 13 } }, h('strong', null, 'Tip: '), 'If an import fails, check the source URL and credentials, then try again.')
+      )),
     ),
     h('div', { className: 'card-body-flush' },
       h('table', null,

package/dist/dashboard/pages/knowledge.js

@@ -2,6 +2,7 @@ import { h, useState, useEffect, useCallback, Fragment, useApp, engineCall, getO
 import { I } from '../components/icons.js';
 import { Modal } from '../components/modal.js';
 import { KnowledgeImportWizard, ImportJobsList } from './knowledge-import.js';
+import { HelpButton } from '../components/help-button.js';
 
 export function KnowledgeBasePage() {
   const { toast } = useApp();
@@ -120,6 +121,10 @@ export function KnowledgeBasePage() {
     } catch (e) { toast(e.message, 'error'); }
   };
 
+  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 };
+
   // ── Detail View ──
   if (selected) {
     return h(Fragment, null,
@@ -128,7 +133,16 @@ export function KnowledgeBasePage() {
           h('button', { className: 'btn btn-secondary btn-sm', onClick: () => setSelected(null) }, '\u2190 Back'),
           editing
             ? h('input', { className: 'input', value: editForm.name, onChange: e => setEditForm(f => ({ ...f, name: e.target.value })), style: { fontSize: 18, fontWeight: 700, padding: '4px 8px' } })
-            : h('h1', { style: { fontSize: 20, fontWeight: 700, margin: 0 } }, selected.name)
+            : h('h1', { style: { fontSize: 20, fontWeight: 700, margin: 0, display: 'flex', alignItems: 'center' } }, selected.name, h(HelpButton, { label: 'Knowledge Base Detail' },
+                h('p', null, 'This is the detail view for a single knowledge base. Here you can manage documents, view chunks, and import new content.'),
+                h('h4', { style: _h4 }, 'Key Actions'),
+                h('ul', { style: _ul },
+                  h('li', null, h('strong', null, 'Import Docs'), ' — Add documents from GitHub, Google Drive, websites, or file uploads.'),
+                  h('li', null, h('strong', null, 'Edit'), ' — Rename or update the description of this knowledge base.'),
+                  h('li', null, h('strong', null, 'Delete'), ' — Permanently remove this knowledge base and all its documents.')
+                ),
+                h('div', { style: _tip }, h('strong', null, 'Tip: '), 'Click a document on the left to preview its chunks on the right. You can edit individual chunks for fine-grained control.')
+              ))
         ),
         h('div', { style: { display: 'flex', gap: 8 } },
           editing
@@ -162,13 +176,13 @@ export function KnowledgeBasePage() {
       // Stats
       selected.stats && h('div', { style: { display: 'grid', gridTemplateColumns: 'repeat(4, 1fr)', gap: 12, marginBottom: 16 } },
         [
-          { label: 'Documents', value: selected.stats?.documentCount || selected.stats?.documents || selected.stats?.totalDocuments || docs.length },
-          { label: 'Chunks', value: selected.stats?.chunkCount || selected.stats?.chunks || selected.stats?.totalChunks || 0 },
-          { label: 'Total Tokens', value: selected.stats?.totalTokens || 0 },
-          { label: 'Queries', value: selected.stats?.queryCount || 0 },
+          { label: 'Documents', value: selected.stats?.documentCount || selected.stats?.documents || selected.stats?.totalDocuments || docs.length, help: 'Total number of source documents imported into this knowledge base.' },
+          { label: 'Chunks', value: selected.stats?.chunkCount || selected.stats?.chunks || selected.stats?.totalChunks || 0, help: 'Total text segments created from your documents. More chunks = more granular retrieval.' },
+          { label: 'Total Tokens', value: selected.stats?.totalTokens || 0, help: 'Total token count across all chunks. This affects storage costs and retrieval context size.' },
+          { label: 'Queries', value: selected.stats?.queryCount || 0, help: 'Number of times agents have searched this knowledge base. Higher usage means this KB is valuable.' },
         ].map(s => h('div', { key: s.label, className: 'card', style: { textAlign: 'center', padding: 12 } },
           h('div', { style: { fontSize: 22, fontWeight: 700, color: 'var(--brand-color, #6366f1)' } }, typeof s.value === 'number' && s.value > 1000 ? (s.value / 1000).toFixed(1) + 'K' : s.value),
-          h('div', { style: { fontSize: 12, color: 'var(--text-muted)', marginTop: 2 } }, s.label)
+          h('div', { style: { fontSize: 12, color: 'var(--text-muted)', marginTop: 2, display: 'flex', alignItems: 'center', justifyContent: 'center' } }, s.label, h(HelpButton, { label: s.label }, h('p', null, s.help)))
         ))
       ),
 
@@ -179,7 +193,16 @@ export function KnowledgeBasePage() {
         h('div', { className: 'card' },
           h('div', { className: 'card-header' },
             h('div', { style: { display: 'flex', justifyContent: 'space-between', alignItems: 'center' } },
-              h('h3', { style: { margin: 0 } }, 'Documents'),
+              h('h3', { style: { margin: 0, display: 'flex', alignItems: 'center' } }, 'Documents', h(HelpButton, { label: 'Documents' },
+                h('p', null, 'Documents are the source files you\'ve imported into this knowledge base. Each document is automatically split into smaller chunks for efficient retrieval.'),
+                h('h4', { style: _h4 }, 'Managing Documents'),
+                h('ul', { style: _ul },
+                  h('li', null, h('strong', null, 'Click'), ' a document to view its chunks in the right panel.'),
+                  h('li', null, h('strong', null, 'Rename'), ' — Click the edit icon to rename a document.'),
+                  h('li', null, h('strong', null, 'Delete'), ' — Remove a document and all its chunks.')
+                ),
+                h('div', { style: _tip }, h('strong', null, 'Tip: '), 'Use "Import Docs" to add more documents from various sources like GitHub, Google Drive, or direct file upload.')
+              )),
               h('span', { className: 'badge badge-neutral' }, docs.length)
             )
           ),
@@ -218,7 +241,16 @@ export function KnowledgeBasePage() {
         // Chunk preview
         h('div', { className: 'card' },
           h('div', { className: 'card-header' },
-            h('h3', { style: { margin: 0 } }, selectedDoc ? 'Chunks: ' + (selectedDoc.name || selectedDoc.id) : 'Select a document')
+            h('h3', { style: { margin: 0, display: 'flex', alignItems: 'center' } }, selectedDoc ? 'Chunks: ' + (selectedDoc.name || selectedDoc.id) : 'Select a document', h(HelpButton, { label: 'Chunks' },
+              h('p', null, 'Chunks are the smaller text segments that documents are split into for RAG (Retrieval-Augmented Generation). When an agent queries the knowledge base, the most relevant chunks are retrieved and included in the prompt.'),
+              h('h4', { style: _h4 }, 'Why Chunks Matter'),
+              h('ul', { style: _ul },
+                h('li', null, h('strong', null, 'Granularity'), ' — Smaller chunks allow more precise retrieval of relevant information.'),
+                h('li', null, h('strong', null, 'Token count'), ' — Each chunk has a token count that affects how much context is used.'),
+                h('li', null, h('strong', null, 'Editing'), ' — You can manually edit chunks to improve quality or fix errors.')
+              ),
+              h('div', { style: _tip }, h('strong', null, 'Tip: '), 'If an agent gives incorrect answers, check the relevant chunks — you may need to edit them for clarity or accuracy.')
+            ))
           ),
           h('div', { className: 'card-body', style: { maxHeight: 500, overflow: 'auto' } },
             !selectedDoc
@@ -267,7 +299,17 @@ export function KnowledgeBasePage() {
   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 } }, 'Knowledge Bases'),
+        h('h1', { style: { fontSize: 20, fontWeight: 700, display: 'flex', alignItems: 'center' } }, 'Knowledge Bases', h(HelpButton, { label: 'Knowledge Bases' },
+          h('p', null, 'Knowledge bases store documents that your agents can search and reference when answering questions. This is the foundation of RAG (Retrieval-Augmented Generation).'),
+          h('h4', { style: _h4 }, 'How It Works'),
+          h('ul', { style: _ul },
+            h('li', null, h('strong', null, 'Create'), ' a knowledge base to organize related documents together.'),
+            h('li', null, h('strong', null, 'Import'), ' documents from GitHub, Google Drive, SharePoint, websites, or file uploads.'),
+            h('li', null, h('strong', null, 'Assign'), ' knowledge bases to agents so they can search and retrieve relevant information.'),
+            h('li', null, h('strong', null, 'Query'), ' — When an agent needs information, it searches the knowledge base and retrieves the most relevant chunks.')
+          ),
+          h('div', { style: _tip }, h('strong', null, 'Tip: '), 'Organize knowledge bases by topic or department. Smaller, focused knowledge bases often produce better search results than one large one.')
+        )),
         h('p', { style: { color: 'var(--text-muted)', fontSize: 13 } }, 'Document ingestion and RAG retrieval for agents')
       ),
       h('button', { className: 'btn btn-primary', onClick: () => setCreating(true) }, I.plus(), ' New Knowledge Base')

package/dist/dashboard/pages/messages.js

@@ -1,5 +1,6 @@
 import { h, useState, useEffect, useRef, Fragment, useApp, engineCall, buildAgentEmailMap, resolveAgentEmail, buildAgentDataMap, renderAgentBadge, getOrgId } from '../components/utils.js';
 import { I } from '../components/icons.js';
+import { HelpButton } from '../components/help-button.js';
 
 export function MessagesPage() {
   const { toast } = useApp();
@@ -194,16 +195,38 @@ export function MessagesPage() {
     );
   };
 
+  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' },
     // Page header
-    h('div', { className: 'page-header' }, h('h1', null, 'Agent Messages'), h('button', { className: 'btn btn-primary', onClick: () => setShowModal(true) }, I.plus(), ' New Message')),
+    h('div', { className: 'page-header' }, h('h1', { style: { display: 'flex', alignItems: 'center' } }, 'Agent Messages', h(HelpButton, { label: 'Agent Messages' },
+      h('p', null, 'All inter-agent and external communications in one place. See how your agents talk to each other and to the outside world.'),
+      h('h4', { style: _h4 }, 'Message types'),
+      h('ul', { style: _ul },
+        h('li', null, h('strong', null, 'Internal'), ' — Agent-to-agent messages within your organization.'),
+        h('li', null, h('strong', null, 'External'), ' — Messages sent to or received from outside (email, APIs, etc.).'),
+        h('li', null, h('strong', null, 'Tasks/Handoffs'), ' — Structured work delegation between agents.'),
+        h('li', null, h('strong', null, 'Broadcasts'), ' — One-to-many announcements.')
+      ),
+      h('div', { style: _tip }, h('strong', null, 'Tip: '), 'Switch to the Topology tab to visualize which agents communicate most. Click nodes to see communication details.')
+    )), h('button', { className: 'btn btn-primary', onClick: () => setShowModal(true) }, I.plus(), ' New Message')),
 
     // Stats cards
     h('div', { style: { display: 'grid', gridTemplateColumns: 'repeat(auto-fit, minmax(160px, 1fr))', gap: 12, marginBottom: 20 } },
-      h('div', { className: 'stat-card' }, h('div', { className: 'stat-value' }, stats.totalMessages), h('div', { className: 'stat-label' }, 'Total')),
-      h('div', { className: 'stat-card' }, h('div', { className: 'stat-value' }, stats.internalMessages), h('div', { className: 'stat-label' }, 'Internal')),
-      h('div', { className: 'stat-card' }, h('div', { className: 'stat-value' }, stats.externalOutbound), h('div', { className: 'stat-label' }, 'External Out')),
-      h('div', { className: 'stat-card' }, h('div', { className: 'stat-value' }, stats.externalInbound), h('div', { className: 'stat-label' }, 'External In'))
+      h('div', { className: 'stat-card' }, h('div', { className: 'stat-value' }, stats.totalMessages), h('div', { className: 'stat-label', style: { display: 'flex', alignItems: 'center' } }, 'Total', h(HelpButton, { label: 'Total Messages' },
+        h('p', null, 'The total count of all messages across all directions and types.')
+      ))),
+      h('div', { className: 'stat-card' }, h('div', { className: 'stat-value' }, stats.internalMessages), h('div', { className: 'stat-label', style: { display: 'flex', alignItems: 'center' } }, 'Internal', h(HelpButton, { label: 'Internal Messages' },
+        h('p', null, 'Messages exchanged between agents within your organization. High internal traffic usually means healthy collaboration.')
+      ))),
+      h('div', { className: 'stat-card' }, h('div', { className: 'stat-value' }, stats.externalOutbound), h('div', { className: 'stat-label', style: { display: 'flex', alignItems: 'center' } }, 'External Out', h(HelpButton, { label: 'External Outbound' },
+        h('p', null, 'Messages sent by agents to external recipients (customers, partners, APIs). Monitor this to ensure agents aren\'t over-communicating.')
+      ))),
+      h('div', { className: 'stat-card' }, h('div', { className: 'stat-value' }, stats.externalInbound), h('div', { className: 'stat-label', style: { display: 'flex', alignItems: 'center' } }, 'External In', h(HelpButton, { label: 'External Inbound' },
+        h('p', null, 'Messages received from outside your organization. These trigger agent workflows and responses.')
+      )))
     ),
 
     // Main tabs: Messages | Topology

package/dist/dashboard/pages/org-chart.js

@@ -1,5 +1,6 @@
 import { h, useState, useEffect, useCallback, useRef, Fragment, useApp, engineCall, getOrgId } from '../components/utils.js';
 import { I } from '../components/icons.js';
+import { HelpButton } from '../components/help-button.js';
 
 // ─── Layout Constants ────────────────────────────────────
 const NODE_W = 220;
@@ -297,7 +298,23 @@ export function OrgChartPage() {
   return h('div', { style: { height: '100%', display: 'flex', flexDirection: 'column', background: BG, borderRadius: 'var(--radius-lg)', overflow: 'hidden' } },
     // Toolbar
     h('div', { style: { display: 'flex', alignItems: 'center', gap: 12, padding: '12px 20px', borderBottom: '1px solid rgba(255,255,255,0.08)', background: 'rgba(0,0,0,0.3)', flexShrink: 0 } },
-      h('div', { style: { fontWeight: 700, fontSize: 16, color: '#fff' } }, 'Organization Chart'),
+      h('div', { style: { fontWeight: 700, fontSize: 16, color: '#fff', display: 'flex', alignItems: 'center' } }, 'Organization Chart', h(HelpButton, { label: 'Organization Chart' },
+        h('p', null, 'Visual hierarchy of all agents in your organization. Shows reporting relationships, status, and activity at a glance.'),
+        h('h4', { style: { marginTop: 16, marginBottom: 8, fontSize: 14 } }, 'Interactions'),
+        h('ul', { style: { paddingLeft: 20, margin: '4px 0 8px' } },
+          h('li', null, h('strong', null, 'Hover'), ' — Highlights the agent\'s full chain (managers above, reports below) and shows a detail tooltip.'),
+          h('li', null, h('strong', null, 'Scroll'), ' — Zoom in/out.'),
+          h('li', null, h('strong', null, 'Click & drag'), ' — Pan the canvas.'),
+          h('li', null, h('strong', null, 'Fit'), ' — Auto-zoom to fit all agents in view.')
+        ),
+        h('h4', { style: { marginTop: 16, marginBottom: 8, fontSize: 14 } }, 'Node badges'),
+        h('ul', { style: { paddingLeft: 20, margin: '4px 0 8px' } },
+          h('li', null, h('strong', null, 'MGR'), ' — This agent manages other agents.'),
+          h('li', null, h('strong', null, 'N tasks'), ' — Currently active tasks.'),
+          h('li', null, h('strong', null, 'N err'), ' — Errors recorded today.')
+        ),
+        h('div', { style: { marginTop: 12, padding: 12, background: 'var(--bg-secondary, #1e293b)', borderRadius: 'var(--radius, 8px)', fontSize: 13 } }, h('strong', null, 'Tip: '), 'Purple nodes represent external (human) managers. Configure manager relationships in each agent\'s settings.')
+      )),
       h('div', { style: { color: 'rgba(255,255,255,0.4)', fontSize: 13 } }, positioned.length + ' agents'),
       h('div', { style: { flex: 1 } }),
       // Legend