Update help book with recently shipped features

Adds Mail Integration, Usage Analytics, CLI Access, and Paperless-NGX
sections; refreshes stale content (Contacts no longer hidden, External
MCP's HTTP transport, Folders, Bulk Actions, Apple Intelligence provider).

oAI/Resources/Confab.help/Contents/Resources/en.lproj/index.html

@@ -35,13 +35,17 @@
                 <li><a href="#online-mode">Online Mode (Web Search)</a></li>
                 <li><a href="#mcp">MCP (File Access)</a></li>
                 <li><a href="#conversations">Managing Conversations</a></li>
+                <li><a href="#usage-analytics">Usage Statistics &amp; Analytics</a></li>
                 <li><a href="#git-sync">Git Sync (Backup &amp; Sync)</a></li>
                 <li><a href="#email-handler">Email Handler (AI Assistant)</a></li>
                 <li><a href="#shortcuts">Shortcuts (Prompt Templates)</a></li>
                 <li><a href="#agent-skills">Agent Skills (SKILL.md)</a></li>
                 <li><a href="#anytype">Anytype Integration</a></li>
                 <li><a href="#external-mcp">External MCP Servers</a></li>
+                <li><a href="#cli-access">CLI Access</a></li>
                 <li><a href="#personal-data">Personal Data Tools</a></li>
+                <li><a href="#mail-integration">Mail Integration</a></li>
+                <li><a href="#paperless">Paperless-NGX Integration</a></li>
                 <li><a href="#research-agents">Research Agents</a></li>
                 <li><a href="#bash-execution">Bash Execution</a></li>
                 <li><a href="#icloud-backup">iCloud Backup</a></li>
@@ -83,8 +87,13 @@
                     <li><strong>Anthropic</strong> - Claude models (Opus, Sonnet, Haiku) (<a href="https://console.anthropic.com">console.anthropic.com</a>)</li>
                     <li><strong>OpenAI</strong> - GPT-4, GPT-4 Turbo, GPT-3.5 models (<a href="https://platform.openai.com">platform.openai.com</a>)</li>
                     <li><strong>Ollama</strong> - Run models locally on your Mac (<a href="https://ollama.ai">ollama.ai</a>)</li>
+                    <li><strong>Apple Intelligence (On-Device)</strong> <span style="font-size: 0.75em; background: #f90; color: #fff; border-radius: 4px; padding: 1px 5px; vertical-align: middle;">Beta</span> - Apple's on-device Foundation model, free and fully offline, no API key needed</li>
                 </ul>
 
+                <div class="note">
+                    <strong>Note:</strong> Apple Intelligence runs entirely on your Mac via Apple's <code>FoundationModels</code> framework (requires macOS 26+ and a supported Mac). It has a small 4K context window and doesn't support tools (MCP, bash, web search) — best for quick, private, offline questions rather than long or tool-driven conversations. Enable it in Settings → General → Apple Intelligence.
+                </div>
+
                 <h3>Adding an API Key</h3>
                 <ol>
                     <li>Press <kbd>⌘,</kbd> or type <code>/config</code> to open Settings</li>
@@ -583,12 +592,28 @@
                 <code class="command">/delete old-chat</code>
                 <p class="warning"><strong>Warning:</strong> This action cannot be undone.</p>
 
-                <h3>Bulk Delete</h3>
+                <h3>Folders</h3>
-                <p>In the conversation list:</p>
+                <p>Organize conversations into folders, including nested subfolders:</p>
+                <ul>
+                    <li>Click <strong>New Folder</strong> at the top of the conversation list to create a top-level folder</li>
+                    <li>Right-click any folder and choose <strong>New Subfolder</strong> to nest folders inside each other</li>
+                    <li>Right-click a folder for <strong>Rename Folder</strong> or <strong>Delete Folder</strong> (conversations and subfolders inside move up one level rather than being deleted)</li>
+                    <li>Drag a conversation onto a folder to move it, or use <strong>Move to Folder</strong> from its context menu</li>
+                    <li>The Save dialog's folder picker lets you assign a folder when first saving a conversation</li>
+                </ul>
+
+                <h3>Bulk Actions (Multi-Select)</h3>
+                <p>Select multiple conversations at once in the conversation list:</p>
                 <ol>
-                    <li>Click "Select" button</li>
+                    <li>Click the <strong>Select</strong> button</li>
-                    <li>Click conversations to select (checkbox appears)</li>
+                    <li>Click conversations to select them (a checkmark appears on each)</li>
-                    <li>Click "Delete (N)" button</li>
+                    <li>Choose an action from the toolbar:
+                        <ul>
+                            <li><strong>Combine (N)</strong> — merges 2 or more selected conversations into one (available once 2+ are selected)</li>
+                            <li><strong>Move to Folder (N)</strong> — moves all selected conversations into a folder you choose</li>
+                            <li><strong>Delete (N)</strong> — deletes all selected conversations</li>
+                        </ul>
+                    </li>
                 </ol>
 
                 <h3>Exporting Conversations</h3>
@@ -600,6 +625,31 @@
                 <p class="note">Files are saved to your Downloads folder. HTML and PDF export are also available from File → Export as HTML…/PDF…, and per-conversation from the Export submenu in the conversation list's context menu.</p>
             </section>
 
+            <!-- Usage Analytics -->
+            <section id="usage-analytics">
+                <h2>Usage Statistics &amp; Analytics</h2>
+                <p>Track how much you're using Confab — messages, tokens, and cost — both for your current session and across your entire history.</p>
+
+                <h3>Quick Stats</h3>
+                <ul>
+                    <li>Press <kbd>⇧⌘S</kbd> or type <code>/stats</code> to open the Statistics window</li>
+                    <li><strong>Session</strong> tab — provider, model, message count, and cost for the current chat</li>
+                    <li><strong>All-Time</strong> tab — totals across every conversation ever recorded</li>
+                </ul>
+
+                <h3>Detailed Analytics</h3>
+                <p>Click the <strong>📊 chart icon</strong> in the Statistics window to open the full Usage Analytics view:</p>
+                <ul>
+                    <li>Choose a timeframe (e.g. last 7 days, last 30 days)</li>
+                    <li>Switch the metric between <strong>Tokens</strong>, <strong>Questions</strong>, and <strong>Cost</strong></li>
+                    <li>View the trend <strong>Over Time</strong>, or broken down <strong>By Model</strong> and <strong>By Provider</strong></li>
+                </ul>
+
+                <div class="note">
+                    <strong>Note:</strong> Usage is tracked independently of saving a conversation — every message counts toward your statistics even if you never save the chat.
+                </div>
+            </section>
+
             <!-- Git Sync -->
             <section id="git-sync">
                 <h2>Git Sync (Backup &amp; Sync)</h2>
@@ -1450,14 +1500,15 @@ Whenever the user asks you to translate something, translate it to Norwegian Bok
             <!-- External MCP Servers -->
             <section id="external-mcp">
                 <h2>External MCP Servers</h2>
-                <p>Connect any external MCP server that speaks the stdio JSON-RPC protocol (for example <code>safaridriver --mcp</code>) and give the AI access to its tools — no custom integration code needed.</p>
+                <p>Connect any external MCP server and give the AI access to its tools — no custom integration code needed. Two transports are supported: local <strong>stdio</strong> servers (for example <code>safaridriver --mcp</code>) and remote <strong>HTTP</strong> servers.</p>
 
-                <h3>Adding a Server</h3>
+                <h3>Adding a stdio Server</h3>
                 <ol>
                     <li>Press <kbd>⌘,</kbd> to open Settings</li>
                     <li>Go to the <strong>MCP</strong> tab → <strong>External MCP Servers</strong> section</li>
-                    <li>Click <strong>Add Server…</strong></li>
+                    <li>Click <strong>Add Server…</strong> and choose the <strong>stdio</strong> transport</li>
                     <li>Enter a <strong>Name</strong> (used to prefix its tools, e.g. "Safari" → <code>safari_navigate_to_url</code>), the <strong>Command</strong> to launch it, and any <strong>Arguments</strong></li>
+                    <li>Optionally add <strong>Environment Variables</strong> the server needs (e.g. an API key it reads at startup)</li>
                     <li>Click <strong>Add</strong> — the server starts automatically and its tools are discovered</li>
                 </ol>
 
@@ -1465,6 +1516,15 @@ Whenever the user asks you to translate something, translate it to Norwegian Bok
                     <strong>💡 Tip:</strong> Arguments containing spaces can be quoted, e.g. <code>--root "/Users/you/My Documents"</code>.
                 </div>
 
+                <h3>Adding an HTTP Server</h3>
+                <p>For remote MCP servers, choose the <strong>HTTP</strong> transport instead and provide:</p>
+                <ul>
+                    <li><strong>Name</strong> — used to prefix its tools, same as stdio</li>
+                    <li><strong>URL</strong> — the server's HTTP endpoint</li>
+                    <li><strong>Custom Headers</strong> — optional key/value pairs sent with every request (e.g. an <code>Authorization</code> header)</li>
+                </ul>
+                <p class="note">Live-verified against a real Obsidian MCP server integration.</p>
+
                 <h3>Server Status</h3>
                 <p>Each configured server shows a status dot and label:</p>
                 <ul>
@@ -1480,16 +1540,40 @@ Whenever the user asks you to translate something, translate it to Norwegian Bok
                 </div>
             </section>
 
+            <!-- CLI Access -->
+            <section id="cli-access">
+                <h2>CLI Access</h2>
+                <p>Get a one-shot AI reply from your Terminal without opening Confab's window — useful for quick questions from a shell prompt or from scripts.</p>
+
+                <h3>Setup</h3>
+                <ol>
+                    <li>Press <kbd>⌘,</kbd> to open Settings</li>
+                    <li>Go to the <strong>MCP</strong> tab → <strong>CLI Access</strong> section</li>
+                    <li>Toggle <strong>Enable CLI Access</strong> on</li>
+                    <li>Choose a <strong>Provider</strong> and <strong>Model</strong> — this fixed model is used for every CLI request</li>
+                    <li>Copy the shown shell function into your <code>~/.zshrc</code></li>
+                </ol>
+
+                <div class="note">
+                    <strong>Note:</strong> Requires <code>jq</code> (<code>brew install jq</code>) to parse the response in the shell function. Confab must be running for the socket to be available.
+                </div>
+
+                <h3>Usage</h3>
+                <p>After adding the function and reloading your shell (<code>source ~/.zshrc</code>):</p>
+                <code class="command">ai "What's the capital of France?"</code>
+                <p class="note">Returns a plain text reply printed straight to your terminal.</p>
+            </section>
+
             <!-- Personal Data Tools -->
             <section id="personal-data">
                 <h2>Personal Data Tools <span style="font-size: 0.75em; background: #f90; color: #fff; border-radius: 4px; padding: 1px 5px; vertical-align: middle;">Beta</span></h2>
-                <p>Let the AI access your Calendar, Reminders, and Location &amp; Maps to answer questions about your schedule and surroundings. Each service is opt-in and uses Apple's own frameworks (EventKit, CoreLocation, MapKit) with standard macOS permission prompts — nothing goes through a third-party service.</p>
+                <p>Let the AI access your Calendar, Reminders, Contacts, and Location &amp; Maps to answer questions about your schedule, people, and surroundings. Each service is opt-in and uses Apple's own frameworks (EventKit, Contacts, CoreLocation, MapKit) with standard macOS permission prompts — nothing goes through a third-party service.</p>
 
                 <h3>Enabling a Service</h3>
                 <ol>
                     <li>Press <kbd>⌘,</kbd> to open Settings</li>
                     <li>Go to the <strong>MCP</strong> tab → <strong>Personal Data</strong> section</li>
-                    <li>Toggle on the services you want: <strong>Calendar</strong>, <strong>Reminders</strong>, or <strong>Location &amp; Maps</strong></li>
+                    <li>Toggle on the services you want: <strong>Calendar</strong>, <strong>Reminders</strong>, <strong>Contacts</strong>, or <strong>Location &amp; Maps</strong></li>
                     <li>Click <strong>Request Access</strong> next to a service — macOS shows its standard permission prompt</li>
                 </ol>
 
@@ -1497,6 +1581,7 @@ Whenever the user asks you to translate something, translate it to Norwegian Bok
                 <ul>
                     <li><strong>Calendar</strong> — list your calendars and upcoming events, create new events</li>
                     <li><strong>Reminders</strong> — list reminder lists and items, create new reminders, mark reminders complete</li>
+                    <li><strong>Contacts</strong> — search by name, phone number, or email; read your own contact card including relationships (e.g. "my mother") to look up a related person by name</li>
                     <li><strong>Location &amp; Maps</strong> — get your current location, search for places, geocode addresses, and get directions (all read-only)</li>
                 </ul>
 
@@ -1504,15 +1589,74 @@ Whenever the user asks you to translate something, translate it to Norwegian Bok
                     <strong>⚠️ Write actions require approval:</strong> Creating a calendar event or reminder, or completing a reminder, shows an approval sheet first with a plain-language summary of what will happen. Choose <strong>Deny</strong>, <strong>Allow Once</strong>, or <strong>Allow for Session</strong>. Toggle this requirement off in Settings → MCP → Personal Data → Require Approval for Changes.
                 </div>
 
-                <div class="note">
-                    <strong>Note:</strong> Contacts support exists internally but is currently hidden while a macOS permission bug affecting hardened-runtime apps is worked out on Apple's side.
-                </div>
-
                 <h3>Example Prompts</h3>
                 <ul>
                     <li>"What's on my calendar tomorrow?"</li>
                     <li>"Remind me to call the dentist on Friday at 2pm"</li>
                     <li>"How far is the nearest coffee shop from here?"</li>
+                    <li>"Find my mother's phone number"</li>
+                </ul>
+            </section>
+
+            <!-- Mail Integration -->
+            <section id="mail-integration">
+                <h2>Mail Integration</h2>
+                <p>Let the AI search your Apple Mail inbox, read specific messages, and save attachments to disk — for example, finding a receipt and handing it off to Paperless-NGX. Uses AppleScript/Apple Events to talk to Mail.app directly, so no separate email credentials are needed (Mail.app must already be set up with your accounts).</p>
+
+                <h3>Enabling Mail Access</h3>
+                <ol>
+                    <li>Press <kbd>⌘,</kbd> to open Settings</li>
+                    <li>Go to the <strong>MCP</strong> tab → <strong>Mail</strong> section</li>
+                    <li>Toggle <strong>Enable Mail</strong> on</li>
+                    <li>Click <strong>Request Access</strong> — macOS shows a one-time Automation consent dialog asking to let Confab control Mail.app</li>
+                </ol>
+
+                <div class="warning">
+                    <strong>⚠️ Every action requires approval:</strong> Unlike Calendar/Reminders, all four Mail tools — including reads — show an approval sheet before running, since inbox content is more sensitive than calendar data. Choose <strong>Deny</strong>, <strong>Allow Once</strong>, or <strong>Allow for Session</strong>. Toggle this requirement off in Settings → MCP → Mail → Require Approval.
+                </div>
+
+                <h3>What the AI Can Do</h3>
+                <ul>
+                    <li><strong>List accounts</strong> — see which Mail.app accounts are configured</li>
+                    <li><strong>Search</strong> — find messages by sender, subject, date range, or whether they have attachments; optionally scoped to one account/mailbox for speed</li>
+                    <li><strong>Read a message</strong> — get the full content of a specific email</li>
+                    <li><strong>Save an attachment</strong> — save a message's attachment to disk so it can be used elsewhere (e.g. uploaded to Paperless-NGX)</li>
+                </ul>
+
+                <h3>Example Prompts</h3>
+                <ul>
+                    <li>"Find all emails with attachments from Elkjøp in my personal account"</li>
+                    <li>"Save the attachment from that receipt email and upload it to Paperless"</li>
+                    <li>"Read the latest email from my accountant"</li>
+                </ul>
+            </section>
+
+            <!-- Paperless-NGX Integration -->
+            <section id="paperless">
+                <h2>Paperless-NGX Integration <span style="font-size: 0.75em; background: #f90; color: #fff; border-radius: 4px; padding: 1px 5px; vertical-align: middle;">Beta</span></h2>
+                <p>Connect Confab to a self-hosted <a href="https://docs.paperless-ngx.com" target="_blank">Paperless-NGX</a> instance so the AI can search, read, and upload documents in your archive.</p>
+
+                <h3>Setup</h3>
+                <ol>
+                    <li>Press <kbd>⌘,</kbd> to open Settings</li>
+                    <li>Go to the <strong>Paperless</strong> tab</li>
+                    <li>Enable the toggle and enter your instance's <strong>URL</strong> and <strong>API Token</strong> (found in Paperless → Settings → API Tokens)</li>
+                    <li>Click <strong>Test Connection</strong> to confirm it can reach your instance</li>
+                </ol>
+
+                <h3>What the AI Can Do</h3>
+                <ul>
+                    <li><strong>Search</strong> — find documents by keyword</li>
+                    <li><strong>Read</strong> — get a specific document's content and metadata</li>
+                    <li><strong>List</strong> — browse tags, correspondents, and document types</li>
+                    <li><strong>Upload</strong> — add a new document to your archive (e.g. an attachment saved from Mail)</li>
+                </ul>
+
+                <h3>Example Prompts</h3>
+                <ul>
+                    <li>"Search Paperless for invoices from last month"</li>
+                    <li>"What tags do I have in Paperless?"</li>
+                    <li>"Upload this receipt to Paperless"</li>
                 </ul>
             </section>
 
@@ -1620,15 +1764,15 @@ Whenever the user asks you to translate something, translate it to Norwegian Bok
                 </ul>
 
                 <h3>MCP Tab</h3>
+                <p>The MCP tab has its own sidebar with sub-pages for each area below:</p>
                 <ul>
-                    <li>Enable/disable MCP file access</li>
+                    <li><strong>File System</strong> — enable/disable MCP file access, add folders via the <strong>+ Add Folder…</strong> button or by dragging from Finder, configure write/delete/move permissions and gitignore respect</li>
-                    <li>Add folders via the <strong>+ Add Folder…</strong> button, or drag from Finder</li>
-                    <li>Enable/disable write, delete, move, and bash execution permissions</li>
-                    <li>Configure gitignore respect</li>
                     <li><strong>Bash Execution</strong> — enable AI shell access, set working directory, timeout, and approval behaviour (see <a href="#bash-execution">Bash Execution</a>)</li>
                     <li><strong>Research Agents</strong> — let the AI spawn parallel read-only research sub-agents (see <a href="#research-agents">Research Agents</a>)</li>
-                    <li><strong>External MCP Servers</strong> — connect any stdio MCP server for additional tools (see <a href="#external-mcp">External MCP Servers</a>)</li>
+                    <li><strong>External MCP Servers</strong> — connect any stdio or HTTP MCP server for additional tools (see <a href="#external-mcp">External MCP Servers</a>)</li>
-                    <li><strong>Personal Data</strong> — Calendar, Reminders, and Location &amp; Maps access (see <a href="#personal-data">Personal Data Tools</a>)</li>
+                    <li><strong>CLI Access</strong> — get AI replies from your Terminal via a local socket (see <a href="#cli-access">CLI Access</a>)</li>
+                    <li><strong>Personal Data</strong> — Calendar, Reminders, Contacts, and Location &amp; Maps access (see <a href="#personal-data">Personal Data Tools</a>)</li>
+                    <li><strong>Mail</strong> — search, read, and save attachments from Apple Mail (see <a href="#mail-integration">Mail Integration</a>)</li>
                 </ul>
 
                 <h3>Sync Tab</h3>