zubo 0.1.0 → 0.1.2

package/.github/workflows/pages.yml

@@ -0,0 +1,31 @@
+name: Deploy to GitHub Pages
+
+on:
+  push:
+    branches: [main]
+    paths: [site/**]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/configure-pages@v5
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+      - id: deployment
+        uses: actions/deploy-pages@v4

package/CONTRIBUTING.md

@@ -0,0 +1,52 @@
+# Contributing to Zubo
+
+Thanks for your interest in contributing to Zubo! Whether you are fixing a bug, adding a feature, or writing a custom skill, we appreciate the help.
+
+## Getting Started
+
+```bash
+git clone https://github.com/your-org/zubo.git
+cd zubo
+bun install
+zubo setup
+bun run dev
+```
+
+## Making Changes
+
+1. Create a branch off `main` for your work.
+2. Write your code. Zubo is built with Bun and TypeScript, so keep things typed.
+3. Run tests before opening a PR:
+   ```bash
+   bun test
+   ```
+4. Make sure the project type-checks cleanly:
+   ```bash
+   npx tsc --noEmit
+   ```
+
+## Skills
+
+Zubo supports custom skills -- self-contained TypeScript handlers that extend what the agent can do. You can contribute new skills by adding them to `~/.zubo/workspace/skills/`. Each skill is a TypeScript file that exports a handler. If you have an idea for a skill, open an issue first so we can discuss the design.
+
+## Pull Requests
+
+- Give your PR a clear, descriptive title.
+- Explain what you changed and why.
+- Make sure all tests pass and there are no type errors.
+- Keep PRs focused. One concern per PR is easier to review.
+
+## Reporting Bugs
+
+If you run into a problem, please open an issue and include:
+
+- A short description of the bug.
+- Steps to reproduce it.
+- What you expected to happen vs. what actually happened.
+- Your OS and Bun version, if relevant.
+
+## Documentation
+
+For more details on how Zubo works, visit the docs: https://zubo.bot/docs
+
+Thanks again for contributing.

package/README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img src="site/logo.svg" width="80" height="80" alt="Zubo">
+  <img src="https://raw.githubusercontent.com/apwn/zubo/main/site/logo.svg" width="80" height="80" alt="Zubo">
 </p>
 
 <h1 align="center">Zubo</h1>

package/package.json

@@ -1,6 +1,24 @@
 {
   "name": "zubo",
-  "version": "0.1.0",
+  "version": "0.1.2",
+  "description": "Your AI agent that never forgets. Persistent memory, 20+ tools, 6 channels, 11+ LLM providers — runs entirely on your machine.",
+  "license": "MIT",
+  "author": "thomaskanze",
+  "homepage": "https://zubo.bot",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/apwn/zubo.git"
+  },
+  "keywords": [
+    "ai",
+    "agent",
+    "llm",
+    "chatbot",
+    "memory",
+    "tools",
+    "bun",
+    "typescript"
+  ],
   "type": "module",
   "bin": {
     "zubo": "src/index.ts"

package/site/install.sh

@@ -1,98 +1,98 @@
-#!/usr/bin/env bash
-set -euo pipefail
-
-# Zubo Installer
-# Usage: curl -fsSL https://zubo.bot/install.sh | bash
-
-BOLD='\033[1m'
-DIM='\033[2m'
-GREEN='\033[32m'
-YELLOW='\033[33m'
-RED='\033[31m'
-CYAN='\033[36m'
-RESET='\033[0m'
-
-info()  { echo -e "${CYAN}${BOLD}→${RESET} $1"; }
-ok()    { echo -e "${GREEN}${BOLD}✓${RESET} $1"; }
-warn()  { echo -e "${YELLOW}${BOLD}!${RESET} $1"; }
-fail()  { echo -e "${RED}${BOLD}✗${RESET} $1"; exit 1; }
-
-echo ""
-echo -e "${BOLD}  zubo installer${RESET}"
-echo -e "${DIM}  The AI agent that never forgets${RESET}"
-echo ""
-
-# --- OS detection ---
-OS="$(uname -s)"
-ARCH="$(uname -m)"
-
-case "$OS" in
-  Linux*)  PLATFORM="linux" ;;
-  Darwin*) PLATFORM="darwin" ;;
-  *)       fail "Unsupported OS: $OS. Zubo supports macOS and Linux." ;;
-esac
-
-case "$ARCH" in
-  x86_64|amd64) ARCH="x64" ;;
-  arm64|aarch64) ARCH="aarch64" ;;
-  *)             fail "Unsupported architecture: $ARCH" ;;
-esac
-
-info "Detected ${PLATFORM}/${ARCH}"
-
-# --- Install Bun if missing ---
-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..."
-  curl -fsSL https://bun.sh/install | bash
-
-  # Source the updated profile so bun is on PATH
-  export BUN_INSTALL="${HOME}/.bun"
-  export PATH="${BUN_INSTALL}/bin:${PATH}"
-
-  if command -v bun &>/dev/null; then
-    ok "Bun installed (v$(bun --version))"
-  else
-    fail "Bun installation failed. Install manually: https://bun.sh"
-  fi
-fi
-
-# --- Install Zubo ---
-info "Installing Zubo..."
-
-if bun add -g zubo 2>/dev/null; then
-  ok "Zubo installed globally"
-else
-  warn "Global install failed, trying with sudo..."
-  sudo bun add -g zubo || fail "Installation failed. Try: bun add -g zubo"
-  ok "Zubo installed globally (with sudo)"
-fi
-
-# --- Verify ---
-if command -v zubo &>/dev/null; then
-  ZUBO_VERSION=$(zubo --version 2>/dev/null || echo "installed")
-  ok "Zubo is ready (${ZUBO_VERSION})"
-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:"
-    echo ""
-    echo -e "  ${DIM}export PATH=\"\$HOME/.bun/bin:\$PATH\"${RESET}"
-    echo ""
-  else
-    fail "Zubo binary not found after install"
-  fi
-fi
-
-echo ""
-echo -e "${BOLD}  Next steps:${RESET}"
-echo ""
-echo -e "  ${CYAN}1.${RESET} Run the setup wizard:    ${BOLD}zubo setup${RESET}"
-echo -e "  ${CYAN}2.${RESET} Start your agent:        ${BOLD}zubo start${RESET}"
-echo -e "  ${CYAN}3.${RESET} Open the dashboard:      ${BOLD}zubo dashboard${RESET}"
-echo ""
-echo -e "  ${DIM}Docs: https://zubo.bot/docs${RESET}"
-echo ""
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Zubo Installer
+# Usage: curl -fsSL https://zubo.bot/install.sh | bash
+
+BOLD='\033[1m'
+DIM='\033[2m'
+GREEN='\033[32m'
+YELLOW='\033[33m'
+RED='\033[31m'
+CYAN='\033[36m'
+RESET='\033[0m'
+
+info()  { echo -e "${CYAN}${BOLD}→${RESET} $1"; }
+ok()    { echo -e "${GREEN}${BOLD}✓${RESET} $1"; }
+warn()  { echo -e "${YELLOW}${BOLD}!${RESET} $1"; }
+fail()  { echo -e "${RED}${BOLD}✗${RESET} $1"; exit 1; }
+
+echo ""
+echo -e "${BOLD}  zubo installer${RESET}"
+echo -e "${DIM}  The AI agent that never forgets${RESET}"
+echo ""
+
+# --- OS detection ---
+OS="$(uname -s)"
+ARCH="$(uname -m)"
+
+case "$OS" in
+  Linux*)  PLATFORM="linux" ;;
+  Darwin*) PLATFORM="darwin" ;;
+  *)       fail "Unsupported OS: $OS. Zubo supports macOS and Linux." ;;
+esac
+
+case "$ARCH" in
+  x86_64|amd64) ARCH="x64" ;;
+  arm64|aarch64) ARCH="aarch64" ;;
+  *)             fail "Unsupported architecture: $ARCH" ;;
+esac
+
+info "Detected ${PLATFORM}/${ARCH}"
+
+# --- Install Bun if missing ---
+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..."
+  curl -fsSL https://bun.sh/install | bash
+
+  # Source the updated profile so bun is on PATH
+  export BUN_INSTALL="${HOME}/.bun"
+  export PATH="${BUN_INSTALL}/bin:${PATH}"
+
+  if command -v bun &>/dev/null; then
+    ok "Bun installed (v$(bun --version))"
+  else
+    fail "Bun installation failed. Install manually: https://bun.sh"
+  fi
+fi
+
+# --- Install Zubo ---
+info "Installing Zubo..."
+
+if bun add -g zubo 2>/dev/null; then
+  ok "Zubo installed globally"
+else
+  warn "Global install failed, trying with sudo..."
+  sudo bun add -g zubo || fail "Installation failed. Try: bun add -g zubo"
+  ok "Zubo installed globally (with sudo)"
+fi
+
+# --- Verify ---
+if command -v zubo &>/dev/null; then
+  ZUBO_VERSION=$(zubo --version 2>/dev/null || echo "installed")
+  ok "Zubo is ready (${ZUBO_VERSION})"
+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:"
+    echo ""
+    echo -e "  ${DIM}export PATH=\"\$HOME/.bun/bin:\$PATH\"${RESET}"
+    echo ""
+  else
+    fail "Zubo binary not found after install"
+  fi
+fi
+
+echo ""
+echo -e "${BOLD}  Next steps:${RESET}"
+echo ""
+echo -e "  ${CYAN}1.${RESET} Run the setup wizard:    ${BOLD}zubo setup${RESET}"
+echo -e "  ${CYAN}2.${RESET} Start your agent:        ${BOLD}zubo start${RESET}"
+echo -e "  ${CYAN}3.${RESET} Open the dashboard:      ${BOLD}zubo dashboard${RESET}"
+echo ""
+echo -e "  ${DIM}Docs: https://zubo.bot/docs${RESET}"
+echo ""

package/src/channels/webchat.ts

@@ -196,7 +196,7 @@ function getConfigInfo(): {
 function switchModelConfig(provider: string, model: string): { ok: boolean; error?: string } {
   try {
     if (!model) {
-      return { ok: false, error: "Model is required" };
+      return { ok: false, error: "Model name is required. Use the format: provider/model (e.g. anthropic/claude-sonnet-4-5-20250929)" };
     }
 
     const config = JSON.parse(readFileSync(paths.config, "utf-8"));
@@ -297,7 +297,7 @@ function handleDashboardApi(url: URL, req: Request): Response | null {
     return (async () => {
       const body = (await req.json()) as { provider?: string; model?: string };
       if (!body.provider) {
-        return Response.json({ ok: false, error: "provider is required" }, { status: 400 });
+        return Response.json({ ok: false, error: "Provider name is required." }, { status: 400 });
       }
       const result = switchModelConfig(body.provider, body.model ?? "");
       return Response.json(result, { status: result.ok ? 200 : 400 });
@@ -1443,7 +1443,7 @@ export function createWebChatAdapter(
             const check = chatLimiter.check(ip);
             if (!check.allowed) {
               return Response.json(
-                { error: "Rate limit exceeded" },
+                { error: "Too many requests. Please wait a moment and try again." },
                 { status: 429, headers: { "Retry-After": String(Math.ceil((check.retryAfterMs ?? 1000) / 1000)) } }
               );
             }
@@ -1455,7 +1455,7 @@ export function createWebChatAdapter(
             const check = uploadLimiter.check(ip);
             if (!check.allowed) {
               return Response.json(
-                { error: "Rate limit exceeded" },
+                { error: "Too many requests. Please wait a moment and try again." },
                 { status: 429, headers: { "Retry-After": String(Math.ceil((check.retryAfterMs ?? 1000) / 1000)) } }
               );
             }
@@ -1695,7 +1695,7 @@ export function createWebChatAdapter(
 
               const stt = getSttProvider();
               if (!stt) {
-                return Response.json({ error: "STT not configured" }, { status: 400 });
+                return Response.json({ error: "Voice not configured. Add voice settings to your config:\n\nzubo config set voice.stt.provider whisper\nzubo config set voice.stt.apiKey YOUR_OPENAI_API_KEY\n\nThen restart Zubo." }, { status: 400 });
               }
 
               // Transcribe

package/src/model.ts

@@ -4,7 +4,7 @@ import { configExists } from "./config/loader";
 
 function readConfig(): any {
   if (!configExists()) {
-    console.log("Config not found. Run 'zubo setup' first.");
+    console.log("No config found. Run 'zubo setup' to get started.");
     process.exit(1);
   }
   return JSON.parse(readFileSync(paths.config, "utf-8"));
@@ -33,7 +33,7 @@ function showCurrent() {
   } else if (config.anthropicApiKey) {
     console.log(`\n  Active: anthropic/${config.model ?? "claude-sonnet-4-5-20250929"} (legacy config)`);
   } else {
-    console.log("\n  No provider configured.");
+    console.log("\n  No provider configured. Run 'zubo setup' to add one.");
   }
   console.log("");
 }
@@ -95,8 +95,7 @@ function switchModel(target: string) {
   }
 
   // Provider not configured — offer quick setup for known providers
-  console.log(`Provider "${providerName}" is not configured.`);
-  console.log(`Run 'zubo setup' to add it, or edit ~/.zubo/config.json directly.`);
+  console.log(`Provider "${providerName}" is not configured. Run 'zubo setup' to add it.`);
   process.exit(1);
 }
 

package/src/tools/builtin-integrations/google/gmail/handler.ts

@@ -3,7 +3,7 @@ const API = "https://gmail.googleapis.com/gmail/v1/users/me";
 async function getToken(): Promise<string> {
   const Zubo = (globalThis as any).Zubo;
   if (Zubo?.getGoogleToken) return Zubo.getGoogleToken();
-  throw new Error("Google is NOT connected. Use google_oauth with action 'start' to set up Google.");
+  throw new Error("Google is not connected. Ask me to set up Google and I'll walk you through it.");
 }
 
 async function safeApiErr(res: Response, service: string): Promise<string> {
@@ -28,8 +28,8 @@ export default async function (input: Record<string, unknown>): Promise<string>
   } catch (err: any) {
     return JSON.stringify({
       error: err.message,
-      action_required: "Google is NOT connected. The user needs to complete the OAuth 2.0 flow. " +
-        "Ask the user for their Google OAuth client_id (ends with .apps.googleusercontent.com) " +
+      action_required: "Google is not connected. The user needs to set up Google OAuth. " +
+        "Ask them for their Google OAuth client_id (ends with .apps.googleusercontent.com) " +
         "and client_secret (starts with GOCSPX-), then use google_oauth tool with action 'start'.",
     });
   }

package/src/tools/builtin-integrations/google/google_calendar/handler.ts

@@ -3,7 +3,7 @@ const API = "https://www.googleapis.com/calendar/v3";
 async function getToken(): Promise<string> {
   const Zubo = (globalThis as any).Zubo;
   if (Zubo?.getGoogleToken) return Zubo.getGoogleToken();
-  throw new Error("Google is NOT connected. Use google_oauth with action 'start' to set up Google.");
+  throw new Error("Google is not connected. Ask me to set up Google and I'll walk you through it.");
 }
 
 function safeApiErr(status: number, statusText: string, service: string): string {
@@ -17,8 +17,8 @@ export default async function (input: Record<string, unknown>): Promise<string>
   } catch (err: any) {
     return JSON.stringify({
       error: err.message,
-      action_required: "Google is NOT connected. The user needs to complete the OAuth 2.0 flow. " +
-        "Ask the user for their Google OAuth client_id (ends with .apps.googleusercontent.com) " +
+      action_required: "Google is not connected. The user needs to set up Google OAuth. " +
+        "Ask them for their Google OAuth client_id (ends with .apps.googleusercontent.com) " +
         "and client_secret (starts with GOCSPX-), then use google_oauth tool with action 'start'.",
     });
   }

package/src/tools/builtin-integrations/google/google_docs/handler.ts

@@ -3,7 +3,7 @@ const API = "https://docs.googleapis.com/v1/documents";
 async function getToken(): Promise<string> {
   const Zubo = (globalThis as any).Zubo;
   if (Zubo?.getGoogleToken) return Zubo.getGoogleToken();
-  throw new Error("Google is NOT connected. Use google_oauth with action 'start' to set up Google.");
+  throw new Error("Google is not connected. Ask me to set up Google and I'll walk you through it.");
 }
 
 function safeApiErr(status: number, statusText: string, service: string): string {
@@ -17,8 +17,8 @@ export default async function (input: Record<string, unknown>): Promise<string>
   } catch (err: any) {
     return JSON.stringify({
       error: err.message,
-      action_required: "Google is NOT connected. The user needs to complete the OAuth 2.0 flow. " +
-        "Ask the user for their Google OAuth client_id (ends with .apps.googleusercontent.com) " +
+      action_required: "Google is not connected. The user needs to set up Google OAuth. " +
+        "Ask them for their Google OAuth client_id (ends with .apps.googleusercontent.com) " +
         "and client_secret (starts with GOCSPX-), then use google_oauth tool with action 'start'.",
     });
   }

package/src/tools/builtin-integrations/google/google_drive/handler.ts

@@ -3,7 +3,7 @@ const API = "https://www.googleapis.com/drive/v3";
 async function getToken(): Promise<string> {
   const Zubo = (globalThis as any).Zubo;
   if (Zubo?.getGoogleToken) return Zubo.getGoogleToken();
-  throw new Error("Google is NOT connected. Use google_oauth with action 'start' to set up Google.");
+  throw new Error("Google is not connected. Ask me to set up Google and I'll walk you through it.");
 }
 
 function safeApiErr(status: number, statusText: string, service: string): string {
@@ -17,8 +17,8 @@ export default async function (input: Record<string, unknown>): Promise<string>
   } catch (err: any) {
     return JSON.stringify({
       error: err.message,
-      action_required: "Google is NOT connected. The user needs to complete the OAuth 2.0 flow. " +
-        "Ask the user for their Google OAuth client_id (ends with .apps.googleusercontent.com) " +
+      action_required: "Google is not connected. The user needs to set up Google OAuth. " +
+        "Ask them for their Google OAuth client_id (ends with .apps.googleusercontent.com) " +
         "and client_secret (starts with GOCSPX-), then use google_oauth tool with action 'start'.",
     });
   }

package/src/tools/builtin-integrations/google/google_sheets/handler.ts

@@ -3,7 +3,7 @@ const API = "https://sheets.googleapis.com/v4/spreadsheets";
 async function getToken(): Promise<string> {
   const Zubo = (globalThis as any).Zubo;
   if (Zubo?.getGoogleToken) return Zubo.getGoogleToken();
-  throw new Error("Google is NOT connected. Use google_oauth with action 'start' to set up Google.");
+  throw new Error("Google is not connected. Ask me to set up Google and I'll walk you through it.");
 }
 
 function safeApiErr(status: number, statusText: string, service: string): string {
@@ -17,8 +17,8 @@ export default async function (input: Record<string, unknown>): Promise<string>
   } catch (err: any) {
     return JSON.stringify({
       error: err.message,
-      action_required: "Google is NOT connected. The user needs to complete the OAuth 2.0 flow. " +
-        "Ask the user for their Google OAuth client_id (ends with .apps.googleusercontent.com) " +
+      action_required: "Google is not connected. The user needs to set up Google OAuth. " +
+        "Ask them for their Google OAuth client_id (ends with .apps.googleusercontent.com) " +
         "and client_secret (starts with GOCSPX-), then use google_oauth tool with action 'start'.",
     });
   }

package/src/tools/builtin-integrations/jira/jira_issues/handler.ts

@@ -14,7 +14,7 @@ export default async function (input: Record<string, unknown>): Promise<string>
   const email = (globalThis as any).Zubo?.getSecret?.("jira_email");
   const baseUrl = (globalThis as any).Zubo?.getSecret?.("jira_url");
   if (!token || !email || !baseUrl) {
-    return JSON.stringify({ error: "Jira not configured. Set jira_token, jira_email, and jira_url secrets." });
+    return JSON.stringify({ error: "Jira is not connected. Tell me your Jira details and I'll set it up. I need: your Jira URL (e.g. yourteam.atlassian.net), email, and an API token from id.atlassian.net/manage-profile/security/api-tokens." });
   }
 
   // Validate jira_url to prevent SSRF — must be HTTPS and a valid Jira host

package/src/tools/builtin-integrations/linear/linear_issues/handler.ts

@@ -22,7 +22,7 @@ async function gql(token: string, query: string, variables?: any): Promise<any>
 
 export default async function (input: Record<string, unknown>): Promise<string> {
   const token = (globalThis as any).Zubo?.getSecret?.("linear_token");
-  if (!token) return JSON.stringify({ error: "Linear token not configured. Use secret_set to store 'linear_token'." });
+  if (!token) return JSON.stringify({ error: "Linear is not connected. Tell me your Linear API key and I'll set it up. You can create one at linear.app/settings/api." });
 
   const { action, issue_id, title, description, team_id, query, assignee_id, priority } = input as {
     action: string; issue_id?: string; title?: string; description?: string;

package/src/tools/builtin-integrations/slack/slack_messages/handler.ts

@@ -14,7 +14,7 @@ const API = "https://slack.com/api";
 export default async function (input: Record<string, unknown>): Promise<string> {
   const token = (globalThis as any).Zubo?.getSecret?.("slack_token");
   if (!token) {
-    return JSON.stringify({ error: "Slack token not configured. Use secret_set to store 'slack_token'." });
+    return JSON.stringify({ error: "Slack is not connected. Tell me your Slack Bot Token (starts with xoxb-) and I'll set it up." });
   }
 
   const { action, channel, text, query, limit } = input as {

package/src/tools/builtin-integrations/twitter/twitter_posts/handler.ts

@@ -14,7 +14,7 @@ const API = "https://api.twitter.com/2";
 export default async function (input: Record<string, unknown>): Promise<string> {
   const bearer = (globalThis as any).Zubo?.getSecret?.("twitter_bearer_token");
   if (!bearer) {
-    return JSON.stringify({ error: "Twitter bearer token not configured. Use secret_set to store 'twitter_bearer_token'." });
+    return JSON.stringify({ error: "Twitter is not connected. Tell me your Twitter Bearer Token and I'll set it up. You can get one from developer.x.com." });
   }
 
   const { action, text, query, tweet_id, max_results } = input as {
@@ -51,7 +51,7 @@ export default async function (input: Record<string, unknown>): Promise<string>
         const accessToken = (globalThis as any).Zubo?.getSecret?.("twitter_access_token");
         const accessSecret = (globalThis as any).Zubo?.getSecret?.("twitter_access_secret");
         if (!apiKey || !apiSecret || !accessToken || !accessSecret) {
-          return JSON.stringify({ error: "Twitter OAuth credentials not configured. Need twitter_api_key, twitter_api_secret, twitter_access_token, twitter_access_secret." });
+          return JSON.stringify({ error: "Twitter posting requires OAuth credentials. Tell me your API Key, API Secret, Access Token, and Access Secret from developer.x.com and I'll set them up." });
         }
         // Use OAuth 1.0a -- simplified via fetch with pre-computed header
         const oauthHeader = computeOAuth1Header("POST", `${API}/tweets`, {}, apiKey, apiSecret, accessToken, accessSecret);

package/src/tools/builtin-skills/http-request/handler.ts

@@ -26,7 +26,7 @@ function validateUrl(raw: string): void {
   try {
     parsed = new URL(raw);
   } catch {
-    throw new Error(`Invalid URL: ${raw}`);
+    throw new Error(`Invalid URL: "${raw}". Make sure it starts with http:// or https://`);
   }
 
   if (isBlockedHost(parsed.hostname)) {

package/src/tools/builtin-skills/shell/handler.ts

@@ -57,7 +57,7 @@ export default async function (input: Record<string, unknown>): Promise<string>
   // Block obviously destructive commands
   for (const pattern of BLOCKED_PATTERNS) {
     if (pattern.test(command)) {
-      throw new Error(`Blocked: command matches dangerous pattern`);
+      throw new Error(`Blocked: this command is not allowed for safety reasons. Destructive system commands (rm -rf /, mkfs, shutdown, etc.) are restricted.`);
     }
   }
 

package/src/tools/builtin-skills/url-fetch/handler.ts

@@ -12,7 +12,7 @@ export default async function (input: Record<string, unknown>): Promise<string>
   });
 
   if (!res.ok) {
-    throw new Error(`Fetch failed: ${res.status} ${res.statusText}`);
+    throw new Error(`Could not fetch URL (${res.status}). The page may be down or blocking requests.`);
   }
 
   const contentType = res.headers.get("content-type") || "";

package/src/tools/builtin-skills/web-search/handler.ts

@@ -12,7 +12,7 @@ export default async function (input: Record<string, unknown>): Promise<string>
   });
 
   if (!res.ok) {
-    throw new Error(`Search failed: ${res.status} ${res.statusText}`);
+    throw new Error(`Search failed (${res.status}). Try again in a moment.`);
   }
 
   const html = await res.text();

package/src/voice/stt.ts

@@ -48,7 +48,7 @@ export function initStt(config: { provider: string; apiKey: string; model?: stri
       logger.info("STT initialized: Whisper API");
       break;
     default:
-      logger.warn(`Unknown STT provider: ${config.provider}`);
+      logger.warn(`Unknown STT provider: "${config.provider}". Supported: whisper, openai`);
   }
 }
 

package/src/voice/tts.ts

@@ -94,7 +94,7 @@ export function initTts(config: { provider: string; apiKey: string; voice?: stri
       logger.info("TTS initialized: ElevenLabs");
       break;
     default:
-      logger.warn(`Unknown TTS provider: ${config.provider}`);
+      logger.warn(`Unknown TTS provider: "${config.provider}". Supported: openai, elevenlabs`);
   }
 }