@rubytech/taskmaster 1.12.3 → 1.13.1

package/skills/anthropic/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: anthropic
+description: Guide users through connecting Claude — either via Claude Pro sign-in (recommended) or by pasting an Anthropic API key.
+metadata: {"taskmaster":{"emoji":"🔑"}}
+---
+
+# Anthropic / Claude Setup
+
+Walks users through connecting Taskmaster to Claude. There are two paths — Claude Pro sign-in (no API key needed) and direct API key entry. The skill determines which path to offer based on what the user is trying to do and what they already have configured.
+
+## When to activate
+
+- User asks how to connect Claude, get an Anthropic key, or set up their AI
+- User is on the Setup page and asks about the "Connect to Claude" button or API keys
+- BOOTSTRAP detects no working Claude/Anthropic connection
+- User sees an authentication error or "Connection expired" message
+- User asks which provider to choose in the API keys dropdown
+
+## What it unlocks
+
+- Claude as the primary AI model — powers all conversations, reasoning, and tool use
+- Two connection methods: subscription-based (Claude Pro) or pay-per-use (API key)
+
+## References
+
+| Task | When to use | Reference |
+|------|-------------|-----------|
+| Guided setup | User wants help connecting Claude | `references/setup-guide.md` |
+
+Load the reference and follow its instructions.

package/skills/anthropic/references/setup-guide.md

@@ -0,0 +1,146 @@
+# Anthropic / Claude — Setup Guide
+
+Walk the user through connecting Taskmaster to Claude. There are two options — determine which one is right for the user, then guide them through it.
+
+---
+
+## The two options
+
+| | Option A: Claude Pro sign-in | Option B: API key |
+|---|---|---|
+| **Best for** | Users with a Claude Pro/Team/Enterprise subscription | Users who want pay-per-use or don't have a Claude subscription |
+| **Cost** | Included in existing subscription | Pay per API call (requires billing setup at Anthropic) |
+| **How it works** | OAuth sign-in — no key to manage | Paste a secret key from console.anthropic.com |
+| **Setup location** | Setup page → "Connect to Claude" | Setup page → API Keys → Add provider |
+
+---
+
+## Step 1: Determine which option
+
+Ask the user which situation applies:
+
+> "There are two ways to connect Claude:
+>
+> **Option A (recommended):** If you have a **Claude Pro subscription** (the one you use at claude.ai), you can sign in directly — no API key needed. This is the easiest option.
+>
+> **Option B:** If you don't have a Claude subscription, or you prefer pay-per-use, you can paste an **API key** from Anthropic's developer console.
+>
+> Which would you like to do?"
+
+If the user isn't sure:
+
+> "Do you pay for Claude Pro (at claude.ai)? If yes, go with Option A — it's simpler and uses your existing subscription. If you don't have a Claude subscription, go with Option B."
+
+---
+
+## Option A: Claude Pro sign-in (recommended)
+
+This uses OAuth device-code flow — the user signs in on their computer and pastes a code back into Taskmaster.
+
+### A1: Navigate to Setup
+
+> "Go to your Taskmaster **Setup** page. Under **Connect to Claude**, click the **Connect to Claude** button."
+
+If the user can't find it:
+
+> "Open your browser and go to your Taskmaster's address followed by **/setup** — for example: `http://taskmaster.local:18789/setup`. You should see a section called **Connect to Claude** with a button."
+
+### A2: Sign in and copy the code
+
+> "After clicking the button, a sign-in page will open on your computer (or you'll be given a link to open). Sign in with your **Claude account** — the same email you use at claude.ai.
+>
+> After signing in, the page will show a **code**. Copy that code."
+
+### A3: Paste the code
+
+> "Paste the code into Taskmaster where it says to enter the code, then click **Submit**."
+
+### A4: Verify connection
+
+> "You're done when the Claude/LLM status light goes **green**. That means Taskmaster is connected and ready to use your Claude subscription."
+
+If the status light doesn't go green:
+
+> "If the status light stays red or amber, try refreshing the Setup page. If it still doesn't work, the sign-in might have timed out — click **Connect to Claude** again to start over."
+
+**Done.** No further setup needed — OAuth handles everything automatically, including token refresh.
+
+---
+
+## Option B: Paste an API key
+
+This uses a direct API key from Anthropic's developer console. The user pays per API call.
+
+### B1: Get the key from Anthropic
+
+> "You'll need an API key from Anthropic's developer console. Here's how to get one:
+>
+> 1. Go to **console.anthropic.com** in your browser
+> 2. Sign in or create an account (you'll need to set up billing — Anthropic charges per API call)
+> 3. Once logged in, go to **API Keys** (in the left sidebar or top menu)
+> 4. Click **Create Key**
+> 5. Give it a name like **Taskmaster**
+> 6. Copy the key — it starts with **sk-ant-** and is quite long
+>
+> **Copy it now** — Anthropic only shows it once. If you lose it, you'll need to create a new one.
+>
+> Send me the key when you have it."
+
+If the user navigated away or can't find API Keys:
+
+> "On console.anthropic.com, look for **API Keys** in the left sidebar. If you don't see it, click on the **Settings** icon or look under your account menu."
+
+### B2: Verify the key format
+
+When the user sends a key, verify it looks correct:
+
+- Starts with `sk-ant-`
+- Usually 90+ characters long
+
+If it doesn't match:
+
+> "That doesn't look like an Anthropic API key — it should start with **sk-ant-** and be quite long (about 100 characters). Can you check you copied the full key?"
+
+### B3: Store the key
+
+Use the `api_keys` tool to store the key:
+
+```
+api_keys({ action: "set", provider: "anthropic", apiKey: "<the key>" })
+```
+
+The key is applied immediately — no restart needed. Confirm to the user:
+
+> "Done — I've saved your Anthropic API key. Claude is now connected. You can start chatting and I'll use Claude for all my responses."
+
+---
+
+## If the user already has a connection
+
+If the user has a working Claude connection (OAuth or API key) and is asking about API keys for a different reason:
+
+> "You're already connected to Claude — I can see your connection is active. Were you looking to set up a different provider (like OpenAI or Google), or is there a problem with your current connection?"
+
+---
+
+## Troubleshooting
+
+| Problem | Solution |
+|---------|----------|
+| "Connection expired" on Setup page | Try sending a message first — the connection auto-refreshes. Reload the Setup page after. If it persists, click **Connect to Claude** to sign in again. |
+| OAuth code expired before pasting | Click **Connect to Claude** again to get a fresh code. The code is only valid for a few minutes. |
+| API key rejected | Verify it starts with `sk-ant-`. Check that billing is set up on console.anthropic.com — keys don't work without an active billing method. |
+| "Which provider should I pick?" | For most users, **Anthropic / Claude** is the right choice. It powers all of Taskmaster's conversations and reasoning. |
+| User has both OAuth and API key | OAuth takes precedence. If the user wants to switch to an API key, they can disconnect OAuth on the Setup page first. |
+
+---
+
+## Common questions
+
+| Question | Answer |
+|----------|--------|
+| "Is Claude Pro enough?" | Yes — Option A uses your existing Claude Pro subscription. No additional cost. |
+| "How much does the API cost?" | Anthropic charges per API call. For small business use, typical costs are a few dollars per month. See anthropic.com/pricing for current rates. |
+| "Can I use both OAuth and an API key?" | Yes, but OAuth takes precedence when active. The API key acts as a fallback. |
+| "Do I need to restart?" | No — both OAuth and API keys are applied immediately. |
+| "What if my subscription lapses?" | Taskmaster will show a connection error. Renew your subscription or switch to an API key. |

package/skills/google-ai/SKILL.md

@@ -24,6 +24,7 @@ Guides users through obtaining a Google AI (Gemini) API key using browser automa
 
 | Task | When to use | Reference |
 |------|-------------|-----------|
-| Browser-assisted setup | User wants help getting the key | `references/browser-setup.md` |
+| Guided setup (conversational) | User asks for help getting the key (default) | `references/setup-guide.md` |
+| Browser-assisted setup | Browser tool available and user wants hands-free setup | `references/browser-setup.md` |
 
-Load the reference and follow its instructions. Send screenshots at each step so the user can see progress.
+Load the appropriate reference and follow its instructions. Prefer the conversational guide unless browser automation is available and the user wants a hands-free experience.

package/skills/google-ai/references/setup-guide.md

@@ -0,0 +1,94 @@
+# Google AI — Setup Guide (Conversational)
+
+Walk the user through getting a Google AI (Gemini) API key with step-by-step instructions. Use this guide when browser automation is unavailable or the user prefers to navigate themselves.
+
+---
+
+## Prerequisites
+
+- User has a Google account (Gmail or business email)
+- Chat channel for sending instructions
+
+---
+
+## Step 1: Explain
+
+Tell the user what this is and why they need it:
+
+> "I need a Google AI key so I can understand voice notes and videos you send me. It also powers image generation and acts as a backup AI model.
+>
+> Google AI Studio gives you a free API key — no credit card needed. The whole thing takes about 2 minutes."
+
+## Step 2: Open Google AI Studio
+
+> "Go to **aistudio.google.com/app/apikey** in your browser. Sign in with your Google account if asked."
+
+If the user doesn't have a Google account:
+
+> "You'll need a Google account first. Go to **accounts.google.com** and click **Create account**. Once that's done, come back and we'll get the API key."
+
+## Step 3: Get the key
+
+> "On the API keys page, you'll see one of two things:
+>
+> **If you already have a key listed:** Click on it to see the full key, then copy it.
+>
+> **If there are no keys:** Click **Create API key** and follow any prompts. Google will generate a key for you — copy it.
+>
+> The key starts with **AIza** and is about 39 characters long. Send me the key when you have it."
+
+If the user can't find the page:
+
+> "Go directly to **aistudio.google.com/app/apikey** — that takes you straight to the API keys section. If you see a different page, look for an **API keys** option in the left sidebar or menu."
+
+## Step 4: Verify the key format
+
+When the user sends a key, verify it looks correct:
+
+- Starts with `AIza`
+- About 39 characters long
+
+If it doesn't match:
+
+> "That doesn't look like a Google AI key — it should start with **AIza** and be about 39 characters long. Can you check you copied the right key?"
+
+## Step 5: Store the key
+
+Use the `api_keys` tool to store the key:
+
+```
+api_keys({ action: "set", provider: "google", apiKey: "<the key>" })
+```
+
+The key is applied immediately — no restart needed. Confirm to the user:
+
+> "Done — I've saved the Google AI key. You can send me voice notes and videos now and I'll understand them both. Image generation is also enabled."
+
+---
+
+## If the user already has a Google AI key configured
+
+> "You already have a Google AI key set up. Would you like to replace it with a new key, or is there something else I can help with?"
+
+---
+
+## Troubleshooting
+
+| Problem | Solution |
+|---------|----------|
+| "Enable API" prompt appears | Click the enable button, wait a moment, then proceed. Google may need to activate the API for your account. |
+| Key exists but user can't see the full value | Click on the key name/row in the table to expand it and reveal the full key. |
+| Sign-in required repeatedly | Make sure you're using the same Google account. Try clearing cookies or using an incognito window. |
+| "API key not valid" error after saving | The key may be restricted to specific APIs. On the API keys page, click the key → check that it's unrestricted or includes "Generative Language API". |
+
+---
+
+## Common questions
+
+| Question | Answer |
+|----------|--------|
+| "Is it free?" | Yes — Google AI Studio provides a free tier with generous monthly quotas. No credit card required. |
+| "Do I need to restart?" | No — the key is applied immediately. |
+| "What does it do?" | Powers voice note transcription (audio to text), video analysis (understanding what's in videos you send), image generation, and serves as a backup AI model. |
+| "I already have a Google Cloud API key" | Google Cloud and Google AI Studio are different. You need a key from **aistudio.google.com**, not console.cloud.google.com. |
+| "Can I use this for other Google services?" | The key is specifically for Google's AI models (Gemini). It doesn't affect your Gmail, Drive, or other Google services. |

package/skills/log-review/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: log-review
+description: "Daily log review — scans system and session logs for errors and warnings, triages issues, provides root-cause analysis, and sends a prioritised health report to admins. Advises escalation to Taskmaster support when issues exceed local resolution."
+metadata: {"taskmaster":{"emoji":"🩺"}}
+---
+
+# Log Review
+
+## When to Activate
+
+- Triggered by the daily log review cron job
+- Admin asks to review system health, logs, errors, or warnings
+- Admin asks "are there any issues?", "how is the system doing?", or similar health questions
+
+## Behaviour
+
+Load `references/review-protocol.md` for the full review and analysis protocol.
+
+**Core principle:** Surface issues with analysis and actionable advice — don't dump raw logs. Every issue reported should include what happened, why, and what to do about it.
+
+### Rules
+
+1. **Scan system logs** — use `logs_read(action: "system")` for gateway-level errors and warnings
+2. **Scan session logs** — use `logs_read(action: "sessions")` across all agents for tool failures and agent errors
+3. **Triage by severity** — critical, warning, info. Deduplicate repeated errors.
+4. **Analyse each issue** — plain-language explanation, likely root cause, suggested admin action
+5. **Escalation guidance** — for issues beyond local resolution, advise forwarding this report to the Taskmaster public agent on WhatsApp for support
+6. **All-clear confirmation** — if no issues found, confirm briefly so admins know the review ran
+
+### Output Format
+
+The report should follow this structure:
+
+- **Critical** — service-affecting issues requiring immediate attention
+- **Warnings** — degraded behaviour or emerging problems
+- **Info** — notable patterns worth awareness
+- **Escalation** — if any issues warrant Taskmaster support, advise forwarding this report
+- **Summary** — issue count or all-clear confirmation
+
+### Constraints
+
+- Keep total execution under 2 minutes
+- Be honest — if nothing surfaced, say "all clear" rather than padding the report
+- Use plain language — the admin is not a developer
+- Deduplicate repeated errors — report once with count

package/skills/log-review/cron-template.json

@@ -0,0 +1,21 @@
+{
+  "templateId": "log-review-daily",
+  "name": "🩺 Daily Log Review",
+  "description": "Scans system and session logs for errors and warnings, provides analysis and suggested actions",
+  "enabled": false,
+  "agentId": "admin",
+  "schedule": { "kind": "cron", "expr": "0 17 * * *" },
+  "sessionTarget": "isolated",
+  "wakeMode": "next-heartbeat",
+  "payload": {
+    "kind": "agentTurn",
+    "message": "Run the daily log review. Use the log-review skill.",
+    "deliver": true,
+    "to": "admins",
+    "bestEffortDeliver": true
+  },
+  "isolation": {
+    "postToMainMode": "summary",
+    "postToMainPrefix": "🩺 Log Review"
+  }
+}

package/skills/log-review/references/review-protocol.md

@@ -0,0 +1,65 @@
+# Log Review Protocol
+
+Run this protocol on schedule or when triggered by an admin. Be thorough in analysis but concise in output.
+
+## Step 1: System Log Scan
+
+Use `logs_read` with `action: "system"` to pull recent gateway logs.
+
+Focus on entries containing `[ERROR]` and `[WARN]`. Ignore routine info-level entries unless they reveal a pattern (e.g. repeated restarts, auth refresh cycles).
+
+Look for:
+- Service crashes or unexpected restarts
+- Channel disconnections (WhatsApp, iMessage)
+- Authentication failures or token expiry
+- Integration errors (API calls, webhook failures)
+- Resource warnings (memory, disk, rate limits)
+- Startup errors or configuration problems
+
+## Step 2: Session Log Scan
+
+Use `logs_read` with `action: "sessions"` to pull recent session transcripts across all agents.
+
+Look for:
+- Tool call failures or errors
+- Agent errors or unexpected exceptions
+- Repeated failed operations (retries that never succeed)
+- Sessions that ended abnormally
+- Patterns across agents (same tool failing for multiple agents)
+
+## Step 3: Triage
+
+Categorise each distinct issue by severity:
+
+- **Critical** — service down, channel disconnected, repeated crashes, data loss risk
+- **Warning** — intermittent errors, degraded performance, auth issues approaching expiry, tool failures
+- **Info** — notable but non-urgent patterns (unusual token usage spikes, brief transient errors that self-resolved)
+
+Deduplicate: if the same error appears 50 times, report it once with the count.
+
+## Step 4: Analysis
+
+For each issue provide:
+1. **What happened** — plain language, no jargon. An admin who isn't a developer should understand this.
+2. **Likely root cause** — your best assessment based on the log context
+3. **Suggested action** — what the admin can do (restart gateway, check API key, reconnect WhatsApp, etc.)
+
+Be specific with actions. "Check the logs" is not a useful suggestion — the whole point of this skill is that the admin doesn't have to.
+
+## Step 5: Escalation Guidance
+
+If any issue meets these criteria, advise the admin to escalate to Taskmaster support:
+- Errors that persist across multiple review cycles
+- Issues in core platform code (not configuration or API keys)
+- Unexplained crashes with no clear root cause
+- Data integrity concerns
+
+Escalation advice: tell the admin to forward this report to the Taskmaster public agent on WhatsApp for support.
+
+## Step 6: Compose Report
+
+Follow the output format defined in SKILL.md. The cron job handles delivery automatically — your text response IS the message.
+
+If no issues were found, send a brief all-clear so admins know the review ran successfully. Don't pad the report.
+
+Keep total execution under 2 minutes.

package/skills/openai/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: openai
+description: Guide users through getting an OpenAI API key for alternative AI models.
+metadata: {"taskmaster":{"emoji":"🔑"}}
+---
+
+# OpenAI Setup
+
+Walks users through obtaining an OpenAI API key. OpenAI is an alternative AI provider — most users connect Claude (Anthropic) as their primary model. OpenAI is useful as a secondary option or for users who prefer GPT models.
+
+## When to activate
+
+- User asks for help getting an OpenAI key or connecting GPT models
+- User selects OpenAI from the API keys provider dropdown and needs help
+- User wants to set up an alternative AI model alongside Claude
+
+## What it unlocks
+
+- GPT models as an alternative or fallback AI provider
+- Alternative audio transcription (Whisper)
+
+## References
+
+| Task | When to use | Reference |
+|------|-------------|-----------|
+| Guided setup | User wants help getting the key | `references/setup-guide.md` |
+
+Load the reference and follow its instructions.

package/skills/openai/references/setup-guide.md

@@ -0,0 +1,122 @@
+# OpenAI — Setup Guide
+
+Walk the user through getting an OpenAI API key and adding it to Taskmaster. Guide with clear instructions.
+
+**Important:** OpenAI requires billing setup before API keys work. The user needs a payment method on file with OpenAI. Free trial credits may be available for new accounts, but the user still needs to create a billing account.
+
+---
+
+## Prerequisites
+
+- User wants OpenAI/GPT models as an alternative or fallback provider
+- Chat channel for sending instructions
+
+---
+
+## Step 1: Explain
+
+Tell the user what this is and why they might want it:
+
+> "OpenAI gives you access to GPT models as an alternative AI provider. Most users run on Claude (Anthropic) as the primary model, but you can add OpenAI as a fallback or secondary option.
+>
+> You'll need an OpenAI account with billing set up. I'll walk you through it."
+
+If the user doesn't have Claude connected yet:
+
+> "Before setting up OpenAI, you might want to connect Claude first — it's the primary AI that powers Taskmaster. Would you like to set up Claude instead, or do you specifically want OpenAI?"
+
+## Step 2: Create an OpenAI account (if needed)
+
+> "If you don't already have an OpenAI account:
+>
+> 1. Go to **platform.openai.com** in your browser
+> 2. Click **Sign up**
+> 3. You can sign up with Google, Microsoft, Apple, or an email address
+> 4. Complete the verification steps
+>
+> Let me know when you're logged in."
+
+## Step 3: Set up billing
+
+> "Before an API key will work, you need billing set up:
+>
+> 1. On **platform.openai.com**, click your profile icon (top-right) → **Settings**
+> 2. In the left sidebar, click **Billing**
+> 3. Add a payment method (credit card or debit card)
+> 4. Add some credit — $5 or $10 is plenty to start
+>
+> Let me know when billing is set up."
+
+If the user already has billing:
+
+> "Great — skip ahead to the next step."
+
+## Step 4: Get an API key
+
+> "Now let's get your API key:
+>
+> 1. Go to **platform.openai.com/api-keys** in your browser
+> 2. Click **Create new secret key**
+> 3. Give it a name like **Taskmaster**
+> 4. Click **Create secret key**
+> 5. Copy the key — it starts with **sk-** and is quite long
+>
+> **Copy it now** — OpenAI only shows the full key once. If you lose it, you'll need to create a new one.
+>
+> Send me the key when you have it."
+
+If the user can't find the API keys page:
+
+> "On platform.openai.com, click your profile icon in the top-right corner, then go to **Settings** → **API keys** in the left sidebar. Or go directly to **platform.openai.com/api-keys**."
+
+## Step 5: Verify the key format
+
+When the user sends a key, verify it looks correct:
+
+- Starts with `sk-`
+- Usually 50+ characters long
+
+If it doesn't match:
+
+> "That doesn't look like an OpenAI API key — it should start with **sk-** and be quite long. Can you check you copied the full key?"
+
+## Step 6: Store the key
+
+Use the `api_keys` tool to store the key:
+
+```
+api_keys({ action: "set", provider: "openai", apiKey: "<the key>" })
+```
+
+The key is applied immediately — no restart needed. Confirm to the user:
+
+> "Done — I've saved your OpenAI API key. GPT models are now available as an alternative AI provider."
+
+---
+
+## If the user already has an OpenAI key configured
+
+> "You already have an OpenAI key set up. Would you like to replace it with a new key, or is there something else I can help with?"
+
+---
+
+## Troubleshooting
+
+| Problem | Solution |
+|---------|----------|
+| Key rejected or doesn't work | Check that billing is set up on platform.openai.com. API keys don't work without an active billing method, even on free tier. |
+| "You exceeded your current quota" | The account has run out of credit. Add more credit under Settings → Billing on platform.openai.com. |
+| Can't find API keys page | Go directly to platform.openai.com/api-keys, or use the profile menu → Settings → API keys. |
+| "Create new secret key" button is greyed out | The account may have hit its key limit. Delete an unused key first, or check account permissions. |
+
+---
+
+## Common questions
+
+| Question | Answer |
+|----------|--------|
+| "Do I need OpenAI if I have Claude?" | No — Claude handles everything. OpenAI is optional, as a fallback or alternative. |
+| "How much does it cost?" | OpenAI charges per API call. For small business use, typical costs are a few dollars per month. See openai.com/pricing for current rates. |
+| "Do I need to restart?" | No — the key is applied immediately. |
+| "Can I use this for ChatGPT Plus?" | No — ChatGPT Plus is a separate subscription for chat.openai.com. API keys are for the developer platform and are billed separately. |
+| "Which GPT model will it use?" | Taskmaster selects the best available model automatically based on your configuration. |

package/taskmaster-docs/USER-GUIDE.md

@@ -144,7 +144,7 @@ After setup, you'll see a navigation bar at the top of the screen linking to all
 | **Contacts** | Manage verified contact records (payment status, account details) that your assistant can look up but not change |
 | **Files** | Browse and manage your assistant's knowledge files and memory |
 | **Browser** | See what the assistant sees when it browses the web for you |
-| **Advanced** | View events (automated tasks), sessions, skills, and logs |
+| **Advanced** | Opening hours, events (automated tasks), skills, and logs |
 
 You'll land on the Setup page by default. From there, the nav bar takes you anywhere.
 
@@ -568,6 +568,7 @@ Your assistant can check and manage many system settings directly through chat
 | Channel settings | Change the AI model, thinking level, DM policy, or group chat policy for your WhatsApp accounts |
 | Branding | Update your accent or background colour |
 | Public chat | Enable or disable the public chat widget, change the greeting, set visitor verification |
+| Opening hours | Check, set, or toggle business opening hours |
 | Skills | List, create, delete, or toggle skills |
 | Logs | Review system and session logs for troubleshooting |
 
@@ -577,6 +578,8 @@ Your assistant can check and manage many system settings directly through chat
 - "Is WhatsApp connected?"
 - "Switch WhatsApp to a cheaper model"
 - "Change the accent colour to blue"
+- "Set opening hours to Mon-Fri 9am to 5pm"
+- "Are we currently open?"
 - "Enable public chat"
 - "Show me the recent logs"
 
@@ -828,7 +831,33 @@ To remove all custom branding and return to the default colours, open the Brandi
 
 ## Advanced
 
-The **Advanced** page has four tabs for monitoring and managing your assistant behind the scenes. You don't need these day-to-day, but they're useful when you want to see what's happening under the hood.
+The **Advanced** page has five tabs for monitoring and managing your assistant behind the scenes. You don't need these day-to-day, but they're useful when you want to see what's happening under the hood.
+
+### Opening Hours
+
+The Opening Hours tab has two independent switches that control when your public assistant responds to customers:
+
+- **Public agent responds** — master switch. Turn this off to silence the assistant entirely, regardless of schedule. Useful when you want to handle all messages manually for a while.
+- **Enable opening hours** — schedule gate. When on, the assistant only responds during the hours you configure. Outside those hours it goes fully silent — no reply, no read receipt, no acknowledgement.
+
+To set up a schedule:
+
+1. Go to the **Advanced** page and select the **Opening Hours** tab
+2. Make sure **Public agent responds** is on
+3. Toggle **Enable opening hours** on
+4. Set the **weekly schedule** — for each day, enter opening and closing times (e.g., 09:00–17:00), or tick **Closed** to mark the day as fully closed
+5. Optionally add **closed dates** for specific days (e.g., bank holidays, annual leave)
+6. Tap **Save**
+
+Changes take effect on the next incoming message — no restart needed. Times are in your local timezone — the system detects it automatically.
+
+**What happens when the assistant is silent (agent off or outside hours):**
+
+- Customer messages on WhatsApp stay as "delivered" (grey ticks) — read receipts are suppressed so customers don't see "read" with no reply
+- Messages are stored in the conversation history so the assistant picks up context when it resumes
+- If you reply manually via WhatsApp, the assistant is aware of your reply and won't contradict it when it resumes
+
+You can also ask your admin assistant to check or change these settings in chat using the `opening_hours` command.
 
 ### Events