@agenticmail/enterprise 0.5.198 → 0.5.200

package/src/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/src/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/src/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/src/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/src/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/src/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

package/src/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/src/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/src/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/src/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')
     ),