@rubytech/taskmaster 1.0.98 → 1.0.99

package/skills/image-gen/references/troubleshooting.md

@@ -0,0 +1,93 @@
+# Image Generation — Troubleshooting
+
+When `image_generate` fails, diagnose the error and guide the user through resolution. Many issues are fixable in-session using the browser tool.
+
+---
+
+## Quota Exceeded
+
+**Symptoms:** Error contains "quota", "rate limit", "429", or "resource exhausted".
+
+The free Google AI tier has daily generation limits. This is the most common failure.
+
+### Resolution steps
+
+1. **Explain clearly** — "The Google AI free tier has a daily image generation limit, and we've hit it."
+
+2. **Offer to check quota together** — Use the browser tool to navigate to the Google AI Studio billing/quota page so the user can see their current usage:
+   - Navigate to `https://aistudio.google.com/apikey`
+   - Take a screenshot and send it — "Here's your current API key dashboard."
+   - Look for quota/usage indicators on the page
+
+3. **Present options based on what you find:**
+   - **Wait for reset** — free tier quotas reset daily. Tell the user approximately when.
+   - **Upgrade the plan** — offer to navigate to billing: `https://aistudio.google.com/plan` or `https://ai.google.dev/pricing`. Walk them through upgrading to pay-as-you-go if they want. Take screenshots at each step.
+   - **Try a different model** — Imagen and Gemini have separate quotas. If one is exhausted, try the other family.
+   - **Reduce usage** — suggest lower resolution (1K instead of 2K/4K), fewer images per request (Imagen), or simpler prompts.
+
+4. **If the user wants to upgrade**, guide them through it with browser automation — same pattern as the `google-ai` key setup skill. Navigate, screenshot, explain each step.
+
+---
+
+## API Key Missing or Invalid
+
+**Symptoms:** Error contains "API key", "authentication", "401", "403", or "PERMISSION_DENIED".
+
+### Resolution steps
+
+1. **Check if key exists** — use `api_keys({ action: "list" })` to verify the Google key is set.
+2. **If missing** — activate the `google-ai` skill to guide browser-assisted key setup.
+3. **If present but invalid** — the key may have been revoked or restricted. Offer to navigate to `https://aistudio.google.com/apikey` to verify the key is still active and create a new one if needed. Store the new key with `api_keys({ action: "set", provider: "google", apiKey: "<key>" })`.
+
+---
+
+## Content Policy Rejection
+
+**Symptoms:** Error contains "safety", "blocked", "policy", "SAFETY", or "content filter".
+
+Google's models refuse to generate certain content (violence, explicit material, real public figures, copyrighted characters).
+
+### Resolution steps
+
+1. **Explain the constraint** — "Google's image models have content safety filters. The prompt triggered one of them."
+2. **Suggest prompt adjustments:**
+   - Make the subject more generic ("a cartoon dog" instead of a specific character)
+   - Remove potentially sensitive elements
+   - Rephrase to be less ambiguous
+3. **Try a different model** — Imagen and Gemini have different safety thresholds. One may accept what the other rejects.
+4. **For person-related rejections** — if using Imagen, check the `personGeneration` parameter. `dont_allow` is most restrictive, `allow_adult` is default.
+
+---
+
+## Model Not Available
+
+**Symptoms:** Error contains "model not found", "not supported", "404".
+
+Preview models (like `gemini-3-pro-image-preview`) may be temporarily unavailable or deprecated.
+
+### Resolution steps
+
+1. **Fall back to a stable model** — try `gemini-2.5-flash-image` (most reliable) or `imagen-4.0-generate-001`.
+2. **If all models fail** — there may be a regional or account restriction. Check `https://ai.google.dev/gemini-api/docs/models` for current availability.
+
+---
+
+## Network or Timeout Errors
+
+**Symptoms:** Error contains "timeout", "ECONNREFUSED", "network", or "fetch failed".
+
+### Resolution steps
+
+1. **Retry once** — transient network issues resolve on retry.
+2. **If persistent** — check internet connectivity. Image generation requires outbound HTTPS to `generativelanguage.googleapis.com`.
+
+---
+
+## General Approach
+
+When any error occurs:
+
+1. **Read the error message carefully** — it usually indicates the category above.
+2. **Don't give up after one failure** — diagnose, explain, and offer a concrete next step.
+3. **Use the browser tool proactively** — offer to navigate to relevant Google pages so you can investigate together. This is a collaborative troubleshooting session, not a dead end.
+4. **Always tell the user what happened and why** — no vague "something went wrong" messages. Be specific about the error and what it means.

package/taskmaster-docs/USER-GUIDE.md

@@ -23,7 +23,7 @@ If you received a Taskmaster device:
 2. Plug it into a wall socket or power strip
 3. Wait about 2 minutes for it to start up
 
-> **WiFi:** Your device needs an internet connection. You can plug a network cable directly into it, or connect a monitor and keyboard to set up WiFi (see "Using Your Pi as a Desktop" below). Need help? Message us on WhatsApp at **+44 7591 215452** or visit [taskmaster.bot](https://www.taskmaster.bot/).
+> **WiFi:** Your device needs an internet connection. You can plug a network cable directly into it to get started, then connect to WiFi from the Control Panel (see "WiFi" below). Need help? Message us on WhatsApp at **+44 7591 215452** or visit [taskmaster.bot](https://www.taskmaster.bot/).
 
 Then open your web browser on any device connected to the same WiFi and go to:
 
@@ -39,7 +39,7 @@ You'll need a monitor, keyboard, and mouse connected to the Pi.
 2. Run:
 
 ```bash
-curl -fsSL https://taskmaster.bot/install.sh | bash
+curl -fsSL https://taskmaster.bot/install.sh | sudo bash
 ```
 
 3. Wait for it to finish (a few minutes — it installs Node.js if needed)
@@ -52,7 +52,7 @@ curl -fsSL https://taskmaster.bot/install.sh | bash
 Open **Terminal** (search for "Terminal" in Spotlight) and run:
 
 ```bash
-curl -fsSL https://taskmaster.bot/install.sh | bash
+curl -fsSL https://taskmaster.bot/install.sh | sudo bash
 ```
 
 This installs Node.js (if needed), Taskmaster, and sets up the background service. Once finished, open your browser and go to: **http://taskmaster.local:18789/setup**
@@ -60,7 +60,7 @@ This installs Node.js (if needed), Taskmaster, and sets up the background servic
 **Custom port:** If you're running multiple Taskmaster instances (e.g., one on a Pi and one on a Mac), give each a different port:
 
 ```bash
-curl -fsSL https://taskmaster.bot/install.sh | bash -s -- --port 19000
+curl -fsSL https://taskmaster.bot/install.sh | sudo bash -s -- --port 19000
 ```
 
 When using a custom port, the hostname includes the port to avoid conflicts. The setup URL becomes `http://taskmaster-19000.local:19000/setup`.
@@ -325,6 +325,25 @@ Your assistant can analyse photos you send it and read common document formats.
 - "Read the attached invoice and tell me the total"
 - "Summarise the key points from this PDF"
 
+### Image Generation
+
+Your assistant can generate images from text descriptions using Google AI models. Ask for any kind of image — product photos, illustrations, logos, social media graphics — and it will guide you through style and model choices, then generate the image directly in the chat.
+
+| Capability | Description |
+|------------|-------------|
+| Generate images | Create images from text descriptions — photos, illustrations, graphics, logos |
+| Multiple models | Choose from fast drafts (Gemini Flash) to high-fidelity output (Imagen 4 Ultra) |
+| Style guidance | Your assistant helps with style, aspect ratio, lighting, and mood choices |
+| Iterate | Refine results — adjust style, change composition, try a different model |
+
+**Try asking:**
+- "Generate a product photo of a coffee mug on a white background"
+- "Create a watercolour illustration of a sunset over the ocean"
+- "Design a minimalist logo concept for a landscaping business"
+- "Make a social media graphic for a summer sale, 1:1 square format"
+
+Image generation requires a Google AI API key (see API Keys below). Generated images are saved to your workspace and displayed inline in the chat.
+
 ### Voice Notes & Video
 
 When someone sends a voice note, image, or video, your assistant processes it automatically before responding — no extra steps needed.
@@ -467,7 +486,7 @@ These unlock additional capabilities. All are optional — your assistant works
 | Provider | What it unlocks | Free tier? |
 |----------|----------------|------------|
 | **Tavily** | Web search — lets your assistant search the internet | Yes (free plan available) |
-| **Google** | Voice note transcription and video analysis | Yes (limited free tier) |
+| **Google** | Voice note transcription, video analysis, and image generation | Yes (limited free tier) |
 
 > **Note:** Image analysis does not need an extra API key — Claude has built-in vision and analyses images directly.
 
@@ -563,6 +582,7 @@ The setup page shows a **Status Dashboard** with status indicators for each serv
 | **WhatsApp** | Connected | Linked but not connected | Not paired |
 | **iMessage** | Connected | Configured but not running | Not configured |
 | **Software** | Up to date | Update available | Not checked |
+| **WiFi** (Pi only) | Connected to a network | Not connected | NetworkManager not available |
 
 **Your assistant is ready when Gateway and Claude are green.** You can start chatting straight away using the Chat page. WhatsApp and iMessage are optional — connect them when you're ready.
 
@@ -633,6 +653,27 @@ You can filter by:
 
 Both views support **auto-follow** (keeps the view scrolled to the latest entries) and **export** to download a log file.
 
+### WiFi (Raspberry Pi)
+
+If your Pi is connected by Ethernet cable, you can switch to WiFi directly from the Control Panel — no monitor or keyboard needed.
+
+1. Go to the **Setup** page
+2. Find the **WiFi** row in the status dashboard (only appears on Raspberry Pi)
+3. Tap **Scan** — a list of nearby WiFi networks appears, sorted by signal strength
+4. Tap the network you want to connect to
+5. If the network is password-protected, enter the password and tap **Connect** (or press Enter)
+6. The row updates to show the connected network name, signal strength, and IP address
+
+**Signal bars** next to each network name show the signal strength — more lit bars means a stronger signal.
+
+**Disconnecting:** Tap **Disconnect** to drop the current WiFi connection. This is useful if you want to switch back to Ethernet or connect to a different network.
+
+**Closing the list:** Tap **Close** to dismiss the network list without making changes. You can also tap the network you're already connected to (marked with a green tick) to dismiss the list.
+
+**Rescanning:** While the network list is open, tap **Scan** again at the top to refresh the list with the latest networks.
+
+> **Tip:** Connect an Ethernet cable first, open the Control Panel, then use the WiFi row to connect. Once WiFi is working, you can remove the Ethernet cable.
+
 ### Changing Network Settings
 
 You might need to change two network settings after your Pi is deployed:
@@ -1229,6 +1270,26 @@ Click **Disable** on the Internet Access row. The public URL stops working immed
 
 When Internet Access is active, click the copy icon next to the URL to copy it to your clipboard. You can share this URL or embed it on your website.
 
+### Embedding the chat widget on your website
+
+Once Internet Access is enabled, you can add a floating chat button to any website. Add this code just before the closing `</body>` tag:
+
+```html
+<script src="https://YOUR-PUBLIC-URL/public/widget.js"></script>
+<script>
+  Taskmaster.init({
+    server: "https://YOUR-PUBLIC-URL",
+    accountId: "your-account-id"
+  });
+</script>
+```
+
+Replace `YOUR-PUBLIC-URL` with the URL shown on the Internet Access row (e.g. `https://taskmaster.tail0e0afb.ts.net`) and `your-account-id` with your account name (e.g. `taskmaster`).
+
+A chat button appears in the bottom-right corner of the page. Clicking it opens a chat window where visitors can talk to your assistant — no WhatsApp required.
+
+You can optionally set the button colour to match your website by adding `color: "#your-hex-colour"` to the init options.
+
 ---
 
 ## Chat Commands
@@ -1333,7 +1394,7 @@ You don't need to refresh the page — the overlay stays visible during the upda
 You can also update by re-running the install command in Terminal:
 
 ```bash
-curl -fsSL https://taskmaster.bot/install.sh | bash
+curl -fsSL https://taskmaster.bot/install.sh | sudo bash
 ```
 
 This detects your existing installation and upgrades it in place.