zubo 0.1.19 → 0.1.21

package/README.md

@@ -56,7 +56,7 @@ npm i -g zubo      # also works
 Then:
 
 ```bash
-zubo setup         # interactive config wizard
+zubo setup         # interactive config wizard (terminal or browser)
 zubo start         # launch the agent
 ```
 
@@ -118,7 +118,7 @@ Set secrets through natural conversation: *"Set my github_token to ghp_..."*
 ## CLI
 
 ```
-zubo setup                 Interactive configuration wizard
+zubo setup                 Interactive configuration wizard (terminal or browser)
 zubo start [--daemon]      Start the agent
 zubo stop                  Stop the background daemon
 zubo status                Show runtime status

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zubo",
-  "version": "0.1.19",
+  "version": "0.1.21",
   "description": "Your AI agent that never forgets. Persistent memory, 25+ tools, 7 channels, 11+ LLM providers — runs entirely on your machine.",
   "license": "MIT",
   "author": "thomaskanze",

package/site/docs/agents.html

@@ -89,11 +89,11 @@
       <p>By default, Zubo operates as a single agent that handles all messages across every connected channel using a unified session identified as "owner." This default agent has access to all registered tools &mdash; both built-in tools and any user-installed skills &mdash; and its personality and behavior are defined by the system prompt stored at <code>~/.zubo/workspace/SYSTEM.md</code>.</p>
       <p>For many use cases, the default agent is all you need. It can search the web, manage your calendar, write code, read and write memory, and use any skill you install. Custom agents become valuable when you want to restrict tool access, provide specialized instructions, or build multi-step workflows.</p>
 
-      <h2>Custom System Prompt</h2>
+      <h2>Personality</h2>
       <p>The system prompt defines your agent's personality, rules, and background knowledge. There are two ways to customize it:</p>
       <ul>
         <li><strong>Edit the file directly</strong> &mdash; Open <code>~/.zubo/workspace/SYSTEM.md</code> in any text editor and modify it.</li>
-        <li><strong>Use the dashboard</strong> &mdash; Navigate to the System Prompt panel in the web dashboard and edit it there. Changes are saved to <code>SYSTEM.md</code> automatically.</li>
+        <li><strong>Use the dashboard</strong> &mdash; Navigate to the Personality panel in the web dashboard and edit it there. Changes are saved to <code>SYSTEM.md</code> automatically.</li>
       </ul>
       <p>Here is an example <code>SYSTEM.md</code> that defines a personalized assistant:</p>
 <pre><code># System Prompt

package/site/docs/api.html

@@ -200,7 +200,7 @@ file: &lt;document&gt;</code></pre>
   "Status": "running"
 }</code></pre>
 
-      <h3>System Prompt</h3>
+      <h3>Personality</h3>
 <pre><code>GET /api/dashboard/system</code></pre>
       <p>Retrieve the current system prompt.</p>
 <pre><code>PUT /api/dashboard/system
@@ -583,7 +583,7 @@ Content-Type: application/json
 <pre><code>GET /api/dashboard/channel-status</code></pre>
       <p>Returns the configuration and connection status for each channel (webchat, Telegram, Discord, Slack, WhatsApp, Signal). Each channel reports whether it is configured and whether it is currently enabled.</p>
 
-      <h3>Secrets Management</h3>
+      <h3>API Keys Management</h3>
 <pre><code>GET /api/dashboard/secrets</code></pre>
       <p>List all stored secrets. Values are masked in the response for security.</p>
 <pre><code>GET /api/dashboard/secrets/:name</code></pre>

package/site/docs/cli.html

@@ -88,9 +88,14 @@
       <h2>Core Commands</h2>
 
       <h3>zubo setup</h3>
-      <p>Interactive 4-step wizard for first-time configuration. Walks you through the full initial setup process:</p>
+      <p>Interactive 4-step wizard for first-time configuration. When you run it, you'll be asked to choose between two modes:</p>
+      <ul>
+        <li><strong>Terminal</strong> &mdash; Classic step-by-step prompts right in your terminal.</li>
+        <li><strong>Dashboard</strong> &mdash; Opens a beautiful browser-based wizard at <code>http://localhost:&lt;port&gt;</code> with the same steps, auto-detection of local providers (Ollama, LM Studio), and connection testing. Great for non-technical users or if you prefer a visual UI.</li>
+      </ul>
+      <p>Both modes walk you through 4 steps:</p>
       <ol>
-        <li><strong>LLM Provider</strong> &mdash; Choose from 12 supported providers (Anthropic, OpenAI, Google, Groq, Ollama, and more). Enter your API key and select a model. Optionally add a fallback provider for automatic failover.</li>
+        <li><strong>LLM Provider</strong> &mdash; Choose from 15 supported providers (Anthropic, OpenAI, Ollama, Groq, Together, OpenRouter, DeepSeek, xAI, MiniMax, Fireworks, Cerebras, LM Studio, Claude Code, Codex, or any OpenAI-compatible endpoint). Enter your API key and select a model. Optionally add a fallback provider for automatic failover.</li>
         <li><strong>Channels</strong> &mdash; Enable any of 7 messaging channels: Telegram, Discord, Slack, WhatsApp, Signal, and Email. WebChat is always enabled by default. Each channel prompts for its required credentials (bot tokens, webhook URLs, etc.).</li>
         <li><strong>Personalization</strong> &mdash; Name your agent and optionally describe its personality. The name and personality are used in the system prompt and across all channels.</li>
         <li><strong>Smart Routing</strong> &mdash; Optionally set up a fast provider for simple queries (e.g., greetings, factual lookups). Smart routing automatically directs simple messages to a cheaper, faster model while using the primary model for complex tasks &mdash; saving 50&ndash;80% on costs.</li>

package/site/docs/config.html

@@ -251,6 +251,98 @@ zubo config get rateLimit          # Show all rate limit settings</code></pre>
         </tbody>
       </table>
 
+      <!-- ================================================================ -->
+      <h3 id="local-models">Local Models (Ollama &amp; LM Studio)</h3>
+
+      <p>
+        Local models run entirely on your machine — no API keys, no usage fees, and your data never leaves your computer. They're ideal as a primary provider for privacy-focused setups, or as a failover when your internet is down.
+      </p>
+
+      <h4>Ollama</h4>
+
+      <p><a href="https://ollama.com" target="_blank">Ollama</a> is a lightweight runtime for running open-source models locally. It provides an OpenAI-compatible API out of the box.</p>
+
+      <p><strong>Installation:</strong></p>
+<pre><code># macOS (Homebrew)
+brew install ollama
+
+# Linux
+curl -fsSL https://ollama.com/install.sh | sh
+
+# Windows — download from https://ollama.com/download</code></pre>
+
+      <p><strong>Getting started:</strong></p>
+<pre><code># Start the Ollama server (runs on port 11434)
+ollama serve
+
+# Pull a model
+ollama pull llama3.3       # Meta Llama 3.3 (good general-purpose)
+ollama pull mistral        # Mistral 7B (fast, lightweight)
+ollama pull qwen2.5        # Qwen 2.5 (strong multilingual)
+ollama pull deepseek-r1    # DeepSeek R1 (strong reasoning)
+ollama pull gemma2         # Google Gemma 2
+
+# List downloaded models
+ollama list</code></pre>
+
+      <p><strong>Zubo configuration:</strong></p>
+<pre><code>"ollama": {
+  "baseUrl": "http://localhost:11434/v1",
+  "model": "llama3.3",
+  "apiKey": "ollama"
+}</code></pre>
+      <p>The <code>apiKey</code> field is required by the OpenAI-compatible client but Ollama ignores it — any value works.</p>
+
+      <h4>LM Studio</h4>
+
+      <p><a href="https://lmstudio.ai" target="_blank">LM Studio</a> provides a graphical interface for downloading, managing, and running local models. It includes a built-in server that exposes an OpenAI-compatible API.</p>
+
+      <p><strong>Installation:</strong></p>
+      <ol>
+        <li>Download LM Studio from <a href="https://lmstudio.ai" target="_blank">lmstudio.ai</a> (macOS, Windows, Linux)</li>
+        <li>Open LM Studio and browse the model library to download a model</li>
+        <li>Go to the <strong>Local Server</strong> tab in the left sidebar</li>
+        <li>Select your model and click <strong>Start Server</strong> — it runs on port 1234 by default</li>
+      </ol>
+
+      <p><strong>Zubo configuration:</strong></p>
+<pre><code>"lmstudio": {
+  "baseUrl": "http://localhost:1234/v1",
+  "model": "your-model-name",
+  "apiKey": "lm-studio"
+}</code></pre>
+
+      <p><strong>Tip:</strong> Local models work great as a failover. Set a cloud provider as primary and Ollama/LM Studio as the fallback — if your API key runs out or the network drops, Zubo seamlessly falls back to your local model:</p>
+<pre><code>"activeProvider": "anthropic",
+"failover": ["ollama"]</code></pre>
+
+      <h4>CLI Providers (Claude Code &amp; OpenAI Codex)</h4>
+
+      <p>These providers use locally installed CLI tools that handle their own authentication — no API key configuration needed in Zubo.</p>
+
+      <table>
+        <thead>
+          <tr><th>Provider</th><th>CLI Tool</th><th>Install</th><th>Auth</th></tr>
+        </thead>
+        <tbody>
+          <tr>
+            <td><code>claude-code</code></td>
+            <td><code>claude</code></td>
+            <td><code>npm install -g @anthropic-ai/claude-code</code></td>
+            <td>Run <code>claude</code> once to authenticate via browser</td>
+          </tr>
+          <tr>
+            <td><code>codex</code></td>
+            <td><code>codex</code></td>
+            <td><code>npm install -g @openai/codex</code></td>
+            <td>Run <code>codex auth login</code> to authenticate</td>
+          </tr>
+        </tbody>
+      </table>
+
+<pre><code>"claude-code": { "model": "claude-sonnet-4-5-20250929" }
+"codex": { "model": "o4-mini" }</code></pre>
+
       <h3>Multi-Provider Example with Failover</h3>
 
 <pre><code>{

package/site/docs/index.html

@@ -69,7 +69,7 @@
           <a href="/docs/conversations">Conversation History</a>
           <a href="/docs/webhooks">Webhooks</a>
           <a href="/docs/workflows">Visual Workflows</a>
-          <a href="/docs/marketplace">MCP Marketplace</a>
+          <a href="/docs/marketplace">Extensions Marketplace</a>
         </div>
       </div>
       <div class="docs-sidebar-section">
@@ -296,12 +296,14 @@ docker compose up -d</code></pre>
 
 <pre><code>zubo setup</code></pre>
 
-      <p>The interactive setup wizard walks you through 4 steps to get Zubo fully configured:</p>
+      <p>You'll be asked to choose between <strong>Terminal</strong> (classic prompts) or <strong>Dashboard</strong> (a browser-based wizard with visual provider cards, auto-detection, and connection testing). Both paths configure the same thing &mdash; pick whichever you prefer.</p>
+
+      <p>The wizard walks you through 4 steps:</p>
       <ul>
-        <li><strong>Step 1: LLM Provider</strong> &mdash; choose from 12 supported providers (Anthropic, OpenAI, Google Gemini, Ollama, Groq, Together, OpenRouter, DeepSeek, xAI, Fireworks, LM Studio, or any OpenAI-compatible endpoint) and enter your API key. Optionally configure a fallback provider for automatic failover.</li>
+        <li><strong>Step 1: AI Provider</strong> &mdash; choose from 15 supported providers (Anthropic, OpenAI, Ollama, Groq, Together, OpenRouter, DeepSeek, xAI, MiniMax, Fireworks, Cerebras, LM Studio, Claude Code, Codex, or any OpenAI-compatible endpoint) and enter your API key. Optionally configure a fallback provider for automatic failover.</li>
         <li><strong>Step 2: Channels</strong> &mdash; enable any combination of Telegram, Discord, Slack, WhatsApp, Signal, and Email. Enter the required tokens and credentials for each. Web Chat is always on and requires no configuration.</li>
         <li><strong>Step 3: Personalization</strong> &mdash; set your agent's name and describe its personality. This shapes how Zubo talks to you across all channels.</li>
-        <li><strong>Step 4: Smart Routing</strong> &mdash; optionally configure a fast model (e.g., Groq) for simple queries. Smart routing automatically detects low-complexity messages and routes them to the cheaper, faster model, saving 50&ndash;80% on costs without sacrificing quality for complex tasks.</li>
+        <li><strong>Step 4: Smart Cost Savings</strong> &mdash; optionally configure a fast model (e.g., Groq) for simple queries. Smart routing automatically detects low-complexity messages and routes them to the cheaper, faster model, saving 50&ndash;80% on costs without sacrificing quality for complex tasks.</li>
       </ul>
       <p>The wizard also creates the <code>~/.zubo</code> directory and all required subdirectories, generates your <code>~/.zubo/config.json</code> file, and downloads the all-MiniLM-L6-v2 embedding model (~80 MB) for local semantic memory.</p>
 
@@ -622,7 +624,7 @@ zubo start --daemon</code></pre>
         <li><strong>Use <code>zubo start --daemon</code></strong> for always-on operation. Zubo writes a PID file and rotates logs automatically.</li>
         <li><strong>Check <code>zubo status</code> and <code>zubo logs</code></strong> for troubleshooting. The status command shows uptime, memory usage, connected channels, and pending scheduled jobs.</li>
         <li><strong>Back up your data</strong> with <code>zubo export</code> for a full JSON export, or rely on the automatic daily SQLite backups in <code>~/.zubo/workspace/backups/</code>.</li>
-        <li><strong>Enable smart routing</strong> to automatically send simple queries to fast, cheap models. Set <code>smartRouting.enabled</code> to <code>true</code> and configure a <code>fastProvider</code> (e.g., Groq) alongside your primary. This can cut costs significantly.</li>
+        <li><strong>Enable smart cost savings</strong> to automatically send simple queries to fast, cheap models. Set <code>smartRouting.enabled</code> to <code>true</code> and configure a <code>fastProvider</code> (e.g., Groq) alongside your primary. This can cut costs significantly.</li>
         <li><strong>Set a budget</strong> to avoid surprise bills: <code>zubo config set budget.dailyLimit 5</code>. Cost tracking is always active in the dashboard under Analytics &rarr; Costs.</li>
         <li><strong>Configure failover providers</strong> so your agent stays available even if your primary LLM provider has an outage. For example, set Anthropic as primary and Ollama as failover for fully offline operation when the cloud is down.</li>
         <li><strong>Keep skills small and focused</strong> &mdash; one skill per task. This makes them easier to test, share, and debug.</li>
@@ -642,7 +644,7 @@ zubo start --daemon</code></pre>
         <li><a href="/docs/conversations"><strong>Conversation History</strong></a> &mdash; unified cross-channel history with FTS5 search, dashboard browsing, and API access for searching and analyzing past conversations across all channels.</li>
         <li><a href="/docs/webhooks"><strong>Webhooks</strong></a> &mdash; create webhook endpoints for GitHub, Stripe, CI/CD, and any external service. HMAC signature verification, prompt templates with <code>{{payload}}</code> substitution, and dashboard management.</li>
         <li><a href="/docs/workflows"><strong>Visual Workflows</strong></a> &mdash; build multi-step automations with the drag-and-drop workflow builder. Step types (tool, agent, condition, message, delay), triggers (manual, cron, webhook), and template variables.</li>
-        <li><a href="/docs/marketplace"><strong>MCP Marketplace</strong></a> &mdash; browse, install, and manage MCP servers from the official registry. One-click installation with automatic tool registration.</li>
+        <li><a href="/docs/marketplace"><strong>Extensions Marketplace</strong></a> &mdash; browse, install, and manage MCP servers from the official registry. One-click installation with automatic tool registration.</li>
         <li><a href="/docs/integrations"><strong>Integrations</strong></a> &mdash; connect Zubo to GitHub, Google Workspace, Notion, Linear, Jira, and more. <a href="/docs/integrations#oauth">OAuth 2.0 authentication</a> with automatic token refresh, API key setup, and usage examples.</li>
         <li><a href="/docs/security"><strong>Security &amp; Auth</strong></a> &mdash; harden your Zubo instance: API key management, tool permission levels, confirmation tokens, rate limiting, file access restrictions, and network security.</li>
         <li><a href="/docs/api"><strong>API Reference</strong></a> &mdash; complete HTTP API documentation for programmatic access: endpoints, request/response formats, authentication, and WebSocket streaming.</li>

package/site/docs/integrations.html

@@ -101,7 +101,7 @@
       <p>There are three ways to connect a service:</p>
       <ol>
         <li><strong>Chat:</strong> Tell Zubo directly &mdash; for example, <code>"Connect GitHub with token ghp_abc123"</code>. Zubo will store the secret and install the skill pack automatically.</li>
-        <li><strong>Dashboard:</strong> Navigate to Settings &rarr; Secrets &rarr; Add Secret. Enter the secret name and value, then Zubo detects the associated integration and installs the skills.</li>
+        <li><strong>Dashboard:</strong> Navigate to Settings &rarr; API Keys. Enter the secret name and value, then Zubo detects the associated integration and installs the skills.</li>
         <li><strong>CLI:</strong> Run <code>zubo start</code>, then use the <code>connect_service</code> tool programmatically to provide the credentials.</li>
       </ol>
       <p>When you connect a service, Zubo performs the following steps:</p>
@@ -384,11 +384,11 @@ zubo mcp-serve</code></pre>
         </tbody>
       </table>
 
-      <h2 id="managing-secrets">Managing Secrets</h2>
+      <h2 id="managing-secrets">Managing API Keys</h2>
       <p>All integration secrets are managed through the same unified secret system.</p>
       <h3>Dashboard</h3>
       <ul>
-        <li>Navigate to Settings &rarr; Secrets &amp; API Keys</li>
+        <li>Navigate to Settings &rarr; API Keys</li>
         <li>Values are displayed as <code>&bull;&bull;&bull;&bull;&bull;&bull;&bull;&bull;</code> by default</li>
         <li>Click <strong>&ldquo;Reveal&rdquo;</strong> to show the actual secret value</li>
         <li>Click <strong>&ldquo;Edit&rdquo;</strong> to update a secret with a new value</li>

package/site/docs/marketplace.html

@@ -3,18 +3,18 @@
 <head>
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <title>MCP Marketplace — Zubo Docs</title>
+  <title>Extensions Marketplace — Zubo Docs</title>
   <meta name="description" content="Browse, install, and manage MCP servers from the built-in marketplace. Extend Zubo with community-built tools, one-click installs, and automatic configuration.">
   <meta name="theme-color" content="#060608">
   <link rel="canonical" href="https://zubo.bot/docs/marketplace">
-  <meta property="og:title" content="MCP Marketplace — Zubo Docs">
+  <meta property="og:title" content="Extensions Marketplace — Zubo Docs">
   <meta property="og:description" content="Browse, install, and manage MCP servers from the built-in marketplace. Extend Zubo with community-built tools, one-click installs, and automatic configuration.">
   <meta property="og:type" content="website">
   <meta property="og:url" content="https://zubo.bot/docs/marketplace">
   <meta property="og:image" content="https://zubo.bot/og-image.png">
   <meta property="og:site_name" content="Zubo">
   <meta name="twitter:card" content="summary_large_image">
-  <meta name="twitter:title" content="MCP Marketplace — Zubo Docs">
+  <meta name="twitter:title" content="Extensions Marketplace — Zubo Docs">
   <meta name="twitter:description" content="Browse, install, and manage MCP servers from the built-in marketplace. Extend Zubo with community-built tools, one-click installs, and automatic configuration.">
   <meta name="twitter:image" content="https://zubo.bot/og-image.png">
   <meta name="twitter:creator" content="@thomaskanze">
@@ -67,7 +67,7 @@
           <a href="/docs/conversations">Conversation History</a>
           <a href="/docs/webhooks">Webhooks</a>
           <a href="/docs/workflows">Visual Workflows</a>
-          <a href="/docs/marketplace" class="active">MCP Marketplace</a>
+          <a href="/docs/marketplace" class="active">Extensions Marketplace</a>
         </div>
       </div>
       <div class="docs-sidebar-section">
@@ -89,12 +89,12 @@
     </aside>
 
     <main class="docs-content">
-      <div class="docs-breadcrumb"><a href="/">Home</a><span>/</span><a href="/docs/">Docs</a><span>/</span>MCP Marketplace</div>
+      <div class="docs-breadcrumb"><a href="/">Home</a><span>/</span><a href="/docs/">Docs</a><span>/</span>Extensions Marketplace</div>
 
-      <h1>MCP Marketplace</h1>
+      <h1>Extensions Marketplace</h1>
 
       <p>
-        The MCP Marketplace lets you browse, install, and manage MCP (Model Context Protocol) servers from the official registry directly through the Zubo dashboard or API. Instead of manually configuring MCP server commands and arguments, you can discover servers from the community, install them with one click, and have their tools automatically registered in Zubo.
+        The Extensions Marketplace lets you browse, install, and manage MCP (Model Context Protocol) servers from the official registry directly through the Zubo dashboard or API. Instead of manually configuring MCP server commands and arguments, you can discover servers from the community, install them with one click, and have their tools automatically registered in Zubo.
       </p>
 
       <!-- ================================================================ -->
@@ -107,7 +107,7 @@
       <h3>Via the Dashboard</h3>
 
       <ol>
-        <li>Open the web dashboard and navigate to the <strong>MCP</strong> panel in the sidebar.</li>
+        <li>Open the web dashboard and navigate to the <strong>Extensions</strong> panel in the sidebar.</li>
         <li>Click the <strong>Marketplace</strong> tab to view the available servers from the registry.</li>
         <li>Use the search bar to filter servers by name or keyword (e.g., "filesystem", "database", "github").</li>
         <li>Each server card shows the name, description, author, tool count, and install status.</li>
@@ -291,7 +291,7 @@ Content-Type: application/json
     "itemListElement": [
       { "@type": "ListItem", "position": 1, "name": "Home", "item": "https://zubo.bot/" },
       { "@type": "ListItem", "position": 2, "name": "Docs", "item": "https://zubo.bot/docs/" },
-      { "@type": "ListItem", "position": 3, "name": "MCP Marketplace", "item": "https://zubo.bot/docs/marketplace" }
+      { "@type": "ListItem", "position": 3, "name": "Extensions Marketplace", "item": "https://zubo.bot/docs/marketplace" }
     ]
   }
   </script>

package/site/docs/security.html

@@ -169,18 +169,18 @@
 
       <h2 id="secret-management">Secret Management</h2>
       <p>Secrets (API keys, tokens, passwords) are stored securely in the local SQLite <code>secrets</code> table. The agent can use secrets by name but <strong>never sees their actual values</strong> in conversation context.</p>
-      <h3>Storing Secrets</h3>
+      <h3>Storing API Keys</h3>
       <p>There are three ways to store a secret:</p>
       <ul>
         <li><strong>Chat:</strong> Tell Zubo directly &mdash; <code>"Store my GitHub token: ghp_abc123xyz"</code></li>
         <li><strong>Tool:</strong> The <code>secret_set</code> tool can be called programmatically</li>
-        <li><strong>Dashboard:</strong> Navigate to Settings &rarr; Secrets and use the form</li>
+        <li><strong>Dashboard:</strong> Navigate to Settings &rarr; API Keys and use the form</li>
       </ul>
-      <h3>Accessing Secrets in Skills</h3>
+      <h3>Accessing API Keys in Skills</h3>
       <p>User-installed skills can access secrets via environment variables:</p>
 <pre><code>const token = process.env.ZUBO_SECRET_GITHUB_TOKEN;</code></pre>
       <p>Only secrets explicitly declared in the skill manifest are passed to the skill process.</p>
-      <h3>Managing Secrets</h3>
+      <h3>Managing API Keys</h3>
       <ul>
         <li><strong>Dashboard:</strong> View masked values (<code>&bull;&bull;&bull;&bull;&bull;&bull;&bull;&bull;</code>), click &ldquo;Reveal&rdquo; to show the actual value, click &ldquo;Edit&rdquo; to update, or &ldquo;Delete&rdquo; to remove</li>
         <li><strong>Naming:</strong> Secret names must match the pattern <code>[a-z0-9_]+</code> (lowercase alphanumeric and underscores only)</li>

package/site/docs/skills.html

@@ -162,7 +162,7 @@ export default async function (input: Record<string, unknown>): Promise&lt
         <li><strong>Cannot import from Zubo internals</strong> &mdash; skills run in a sandboxed subprocess and have no access to Zubo's core modules, database, or session state</li>
       </ul>
 
-      <h2>Accessing Secrets</h2>
+      <h2>Accessing API Keys</h2>
       <p>Skills often need API keys or credentials to call external services. Zubo provides a secure way to pass secrets to skill handlers via environment variables:</p>
 <pre><code>export default async function (input: Record&lt;string, unknown&gt;): Promise&lt;string&gt; {
   const apiKey = process.env.ZUBO_SECRET_WEATHER_API_KEY;

package/site/docs/webhooks.html

@@ -97,6 +97,23 @@
         Webhooks let external services push events to Zubo in real time. When a webhook receives an event, Zubo processes the payload through a configurable prompt template and takes action automatically. This turns Zubo into a reactive automation hub — connect GitHub for push notifications, Stripe for payment events, CI/CD pipelines for build results, or any service that can send HTTP POST requests.
       </p>
 
+      <!-- ================================================================ -->
+      <h2 id="network-requirements">Network Requirements</h2>
+
+      <div style="background: rgba(245,166,35,0.08); border-left: 3px solid #f5a623; padding: 14px 18px; border-radius: 6px; margin: 16px 0; font-size: 14px; line-height: 1.6;">
+        <strong style="color: #f5a623;">Localhost won't work for external services.</strong> Webhook URLs like <code>http://localhost:61939/api/webhook/...</code> are only reachable from your own machine. External services (GitHub, Stripe, etc.) cannot send events to localhost.
+      </div>
+
+      <p>To receive webhooks from external services, you need a publicly reachable URL. Options:</p>
+
+      <ul>
+        <li><strong>ngrok</strong> &mdash; Run <code>ngrok http 61939</code> to get a public HTTPS URL that tunnels to your local Zubo instance. Free tier available.</li>
+        <li><strong>Cloudflare Tunnel</strong> &mdash; Run <code>cloudflared tunnel --url http://localhost:61939</code> for a free, fast tunnel.</li>
+        <li><strong>Deploy Zubo</strong> &mdash; Run Zubo on a VPS or cloud server with a public IP and domain name.</li>
+      </ul>
+
+      <p>Once you have a public URL, configure the external service to send events to <code>https://your-public-url/api/webhook/&lt;webhook-id&gt;</code>.</p>
+
       <!-- ================================================================ -->
       <h2 id="creating-webhooks">Creating Webhooks</h2>
 

package/site/index.html

@@ -4,18 +4,18 @@
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
   <title>Zubo — Your AI Agent. Your Machine. Your Rules.</title>
-  <meta name="description" content="Open-source AI agent that runs on your machine. One command to install, one file to configure. Persistent memory, 25+ tools, 7 messaging channels, 12+ LLM providers. MCP compatible. Zero complexity.">
+  <meta name="description" content="Open-source AI agent that runs on your machine. One command to install, one file to configure. Persistent memory, 25+ tools, 7 messaging channels, 12+ AI providers. Extension compatible. Zero complexity.">
   <meta name="theme-color" content="#060608">
   <link rel="canonical" href="https://zubo.bot/">
   <meta property="og:title" content="Zubo — Your AI Agent. Your Machine. Your Rules.">
-  <meta property="og:description" content="Open-source AI agent that runs on your machine. Persistent memory, 25+ tools, works across Telegram, Discord, Slack, WhatsApp, Email, and more. MCP compatible. One install, zero cloud.">
+  <meta property="og:description" content="Open-source AI agent that runs on your machine. Persistent memory, 25+ tools, works across Telegram, Discord, Slack, WhatsApp, Email, and more. Extension compatible. One install, zero cloud.">
   <meta property="og:type" content="website">
   <meta property="og:url" content="https://zubo.bot/">
   <meta property="og:image" content="https://zubo.bot/og-image.png">
   <meta property="og:site_name" content="Zubo">
   <meta name="twitter:card" content="summary_large_image">
   <meta name="twitter:title" content="Zubo — Your AI Agent. Your Machine. Your Rules.">
-  <meta name="twitter:description" content="Open-source AI agent that runs on your machine. Persistent memory, 25+ tools, works across Telegram, Discord, Slack, WhatsApp, Email, and more. MCP compatible. One install, zero cloud.">
+  <meta name="twitter:description" content="Open-source AI agent that runs on your machine. Persistent memory, 25+ tools, works across Telegram, Discord, Slack, WhatsApp, Email, and more. Extension compatible. One install, zero cloud.">
   <meta name="twitter:image" content="https://zubo.bot/og-image.png">
   <meta name="twitter:creator" content="@thomaskanze">
   <link rel="preconnect" href="https://fonts.googleapis.com">
@@ -264,7 +264,7 @@
             <svg width="28" height="28" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><path d="M14.7 6.3a1 1 0 0 0 0 1.4l1.6 1.6a1 1 0 0 0 1.4 0l3.77-3.77a6 6 0 0 1-7.94 7.94l-6.91 6.91a2.12 2.12 0 0 1-3-3l6.91-6.91a6 6 0 0 1 7.94-7.94l-3.76 3.76z"/></svg>
           </div>
           <h3>25+ Smart Tools</h3>
-          <p>Web search, file operations, code interpreter, image generation, APIs, webhooks, and more. Knowledge graph memory, MCP support, and sub-agent delegation for complex tasks.</p>
+          <p>Web search, file operations, code interpreter, image generation, APIs, webhooks, and more. Knowledge graph memory, extension support, and sub-agent delegation for complex tasks.</p>
         </div>
 
         <div class="bento-card tilt-card" data-feature="privacy">

package/site/install.sh

@@ -29,7 +29,9 @@ ARCH="$(uname -m)"
 case "$OS" in
   Linux*)  PLATFORM="linux" ;;
   Darwin*) PLATFORM="darwin" ;;
-  *)       fail "Unsupported OS: $OS. Zubo supports macOS and Linux." ;;
+  MINGW*|MSYS*|CYGWIN*)
+           fail "Windows detected. Use WSL (Windows Subsystem for Linux) to run Zubo:\n\n  ${DIM}wsl --install${RESET}\n  Then run this installer inside WSL." ;;
+  *)       fail "Unsupported OS: $OS. Zubo supports macOS, Linux, and Windows (via WSL)." ;;
 esac
 
 case "$ARCH" in
@@ -45,7 +47,7 @@ if command -v bun &>/dev/null; then
   BUN_VERSION=$(bun --version 2>/dev/null || echo "unknown")
   ok "Bun already installed (v${BUN_VERSION})"
 else
-  info "Installing Bun runtime..."
+  info "Installing Bun (a fast JavaScript runtime Zubo needs)..."
   curl -fsSL https://bun.sh/install | bash
 
   # Source the updated profile so bun is on PATH
@@ -55,7 +57,7 @@ else
   if command -v bun &>/dev/null; then
     ok "Bun installed (v$(bun --version))"
   else
-    fail "Bun installation failed. Install manually: https://bun.sh"
+    fail "Bun installation failed. Visit https://bun.sh for manual install instructions."
   fi
 fi
 
@@ -78,9 +80,13 @@ else
   # Bun global bin might not be on PATH yet
   ZUBO_BIN="${HOME}/.bun/bin/zubo"
   if [ -f "$ZUBO_BIN" ]; then
-    warn "Zubo installed but not on PATH. Add this to your shell profile:"
+    warn "Zubo installed but your terminal can't find it yet."
     echo ""
-    echo -e "  ${DIM}export PATH=\"\$HOME/.bun/bin:\$PATH\"${RESET}"
+    echo -e "  Run this command, then restart your terminal:"
+    echo ""
+    echo -e "  ${BOLD}echo 'export PATH=\"\$HOME/.bun/bin:\$PATH\"' >> ~/.bashrc && source ~/.bashrc${RESET}"
+    echo ""
+    echo -e "  ${DIM}(On macOS with zsh, use ~/.zshrc instead of ~/.bashrc)${RESET}"
     echo ""
   else
     fail "Zubo binary not found after install"

package/src/agent/compaction.ts

@@ -35,19 +35,35 @@ export function compactMessages(
     contextWindow: maxTokens,
   });
 
+  // Check if first message is a summary (preserve it during truncation)
+  const hasSummary =
+    messages.length > 0 &&
+    messages[0].role === "user" &&
+    typeof messages[0].content !== "string" &&
+    Array.isArray(messages[0].content) &&
+    messages[0].content.some(
+      (b: any) =>
+        b.type === "text" &&
+        typeof b.text === "string" &&
+        b.text.includes("Previous conversation summary:")
+    );
+
   // Find the start index where cumulative remaining tokens fit under target
-  let startIdx = 0;
+  // Skip index 0 if it's a summary message — we want to keep it
+  let startIdx = hasSummary ? 1 : 0;
   while (startIdx < messages.length - 2 && tokens > target) {
     tokens -= costs[startIdx];
     startIdx++;
   }
 
-  // Ensure first message is from user (Claude API requirement)
+  // Ensure first kept message (after summary) is from user (Claude API requirement)
   while (startIdx < messages.length && messages[startIdx].role !== "user") {
     startIdx++;
   }
 
-  const compacted = messages.slice(startIdx);
-  logger.info("Compaction done", { remainingMessages: compacted.length });
+  const compacted = hasSummary
+    ? [messages[0], ...messages.slice(startIdx)]
+    : messages.slice(startIdx);
+  logger.info("Compaction done", { remainingMessages: compacted.length, preservedSummary: hasSummary });
   return compacted;
 }

package/src/agent/history.ts

@@ -14,13 +14,18 @@ export function recordMessage(
 ): void {
   try {
     const db = getDb();
+    // Ensure thread exists before inserting message
+    db.run(
+      "INSERT OR IGNORE INTO threads (id, title, channel, message_count, created_at, updated_at) VALUES (?, ?, ?, 0, datetime('now'), datetime('now'))",
+      [threadId, threadId, channel ?? "webchat"]
+    );
     db.run(
       "INSERT INTO conversation_messages (thread_id, role, content, channel, timestamp) VALUES (?, ?, ?, ?, datetime('now'))",
       [threadId, role, content, channel ?? null]
     );
     db.run(
-      "UPDATE threads SET message_count = message_count + 1, updated_at = datetime('now') WHERE id = ?",
-      [threadId]
+      "UPDATE threads SET message_count = message_count + 1, updated_at = datetime('now'), channel = COALESCE(channel, ?) WHERE id = ?",
+      [channel ?? "webchat", threadId]
     );
     db.run(
       "INSERT INTO conversation_search (content, thread_id, role) VALUES (?, ?, ?)",