@rubytech/create-realagent 1.0.406

package/payload/platform/plugins/admin/skills/specialist-management/skill.md

@@ -0,0 +1,44 @@
+---
+name: specialist-management
+description: "Install, remove, and manage specialist subagents and premium plugin agents."
+---
+
+# Specialist Management
+
+Manage specialist subagents at any time via conversation.
+
+## Install a specialist
+
+1. Use Bash: `cp $PLATFORM_ROOT/templates/specialists/agents/{name}.md specialists/agents/{name}.md`
+2. Ensure `agents/admin/AGENTS.md` exists; create if absent.
+3. Read `agents/admin/AGENTS.md`, then append: `- **specialists:{name}**: {one-line delegation rule}` using Edit.
+4. Confirm to the user — active from next session start.
+
+## Remove a specialist
+
+1. Use Bash: `rm specialists/agents/{name}.md`
+2. Read `agents/admin/AGENTS.md`, then remove the specialist's line using Edit — match the full line: `- **specialists:{name}**: ...`.
+3. Confirm to the user.
+
+## Premium plugin agents
+
+Premium plugins can include an `agents/` directory alongside `skills/` and `references/`. Agent files use the naming convention `{plugin-name}--{agent-name}.md` — the double-dash separator prevents collisions with core specialists, which never contain `--`.
+
+### Activate premium plugin agents
+
+For each `.md` file in `$PLATFORM_ROOT/plugins/{plugin-name}/agents/`:
+
+1. Check whether `specialists/agents/{filename}` already exists — skip if so (idempotent).
+2. Use Bash: `cp $PLATFORM_ROOT/plugins/{plugin-name}/agents/{filename} specialists/agents/{filename}`
+3. Extract the `name` and `description` fields from the copied file's YAML frontmatter.
+4. Read `agents/admin/AGENTS.md`. If it already contains `specialists:{name}`, skip. Otherwise append: `- **specialists:{name}**: {description}` using Edit.
+5. Confirm each installed specialist to the user — active from next session start.
+
+### Deactivate premium plugin agents
+
+1. Use Bash: `ls specialists/agents/{plugin-name}--*.md` to list matching files.
+2. For each match, use Bash: `rm specialists/agents/{filename}`
+3. Read `agents/admin/AGENTS.md`, then remove each matching line using Edit — match by `specialists:{name}` where `{name}` is extracted from the removed file's frontmatter `name` field.
+4. Confirm removal to the user.
+
+Core specialists (files without `--` in the name) are never affected by premium plugin operations.

package/payload/platform/plugins/admin/skills/stream-log-review/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: stream-log-review
+description: >
+  Analyse a Claude agent stream log file for errors, warnings, and anomalies.
+  Produces a structured diagnostic report with session-by-session breakdown,
+  root-cause analysis for known patterns, and cost/usage summary.
+  Trigger phrases: "review logs", "stream log", "log errors", "log review",
+  "what went wrong", "diagnose the log", "log report".
+---
+
+# Stream Log Review
+
+Analyse Claude agent stream logs — the `claude-agent-stream-*.log` files generated by the platform. Parse the log, identify problems, attempt diagnosis, and produce a structured report.
+
+## When to Activate
+
+- Admin asks to review, diagnose, or analyse a stream log
+- A log file path is provided for analysis
+- Admin asks what went wrong in a session or across sessions
+
+## What a Good Report Looks Like
+
+- Covers every session in the log, segmented by session boundaries
+- Every error and warning is classified by severity with a root-cause diagnosis where patterns are known
+- Errors that repeat across sessions are grouped and counted, not listed individually
+- Causal chains are identified (e.g. DNS failure leading to retry loop leading to context overflow)
+- Cost and token usage are summarised per session and in aggregate
+- Recommendations are actionable — grouped by bugs to fix, infrastructure issues, and agent behaviour problems
+- A non-technical admin can scan it for severity; a developer can use it to prioritise fixes
+
+## Boundaries
+
+- This skill analyses logs. It does not fix the bugs it finds — that's a separate task.
+- Applies to `claude-agent-stream-*.log` files only. SSE event logs and stderr logs are different formats handled by `logs-read` directly.
+- Does not modify or rotate log files.
+- Does not correlate across multiple days — each report covers a single log file.
+
+## References
+
+Load `references/analysis-patterns.md` for the event taxonomy, error classification patterns, diagnosis heuristics, and report format template.

package/payload/platform/plugins/admin/skills/stream-log-review/references/analysis-patterns.md

@@ -0,0 +1,161 @@
+# Stream Log Analysis Patterns
+
+## Log Format
+
+Stream logs contain two interleaved formats:
+
+### Bracketed app-level lines
+
+```
+[2026-03-24T08:36:45.445Z] [tag] key=value key=value …
+```
+
+Tags identify the event type. Key tags:
+
+| Tag | Meaning |
+|-----|---------|
+| `managed-spawn` | New session started. Contains `pid`, `sessionKey`, `historyMessages`, `pluginDir`. This is the **session boundary marker**. |
+| `stdin` | Prompt sent to Claude. `len` = character count, `preview` = first N chars. |
+| `init` | MCP servers connected and tool count. |
+| `tool-use` | Agent called a tool. `name` = tool name, `input` = JSON args. |
+| `tool-result` | Tool returned. `name`, `error` (true/false), `output` (truncated). |
+| `usage` | Token counts for this turn. `input`, `cache_create`, `cache_read`, `output`, `reported_window`. |
+| `modelUsage` | Per-model cost breakdown JSON. Contains `costUSD`. |
+| `context-overflow` | Session exceeded context window. Shows percentage and token counts. |
+| `managed-append` | Response appended to session history. `sessionKey`, `historyAfter`, `responseTextLen`. |
+| `unknown-type` | Unhandled stream event type. Usually `rate_limit_event`. |
+| `subagent-start` / `subagent-end` | Specialist subagent dispatched/returned. |
+| `agent-dispatch` / `agent-return` | Agent tool dispatch/return. |
+| `heartbeat` | Long-running session keepalive. |
+| `active` / `disabled` / `unchanged` | Plugin/tool status during init. |
+| `expanded` | Skill or slash command expanded. |
+| `render-component` / `browser-viewer` | UI component rendered in response. |
+
+### Raw JSON lines
+
+```json
+{"type":"system","subtype":"init", ...}
+{"type":"rate_limit_event", ...}
+{"type":"user","message":{...}, ...}
+{"type":"result","subtype":"success", ...}
+```
+
+The `result` event is the **session result**. It contains `is_error`, `duration_ms`, `num_turns`, `total_cost_usd`, `stop_reason`, `usage`, and `modelUsage`.
+
+## Session Segmentation
+
+Each session begins with a `[managed-spawn]` line and ends with either:
+- A `result` JSON line (normal completion)
+- The next `[managed-spawn]` line (if the session crashed without a result)
+
+Extract `sessionKey` from `managed-spawn` and `session_id` from the `result` JSON.
+
+## Error Classification
+
+### Severity: ERROR
+
+These indicate something broke and the agent could not complete the intended action.
+
+| Pattern | How to detect | Known root cause |
+|---------|--------------|-----------------|
+| **MCP tool failure** | `[tool-result] name=mcp__* error=true` | Tool-specific — read the `output` for the error message |
+| **Neo4j LIMIT float** | `error=true` + output contains `'50.0' is not a valid value` | LIMIT parameter passed as float instead of integer. Fix: wrap with `neo4j.int()` |
+| **Bash command not found** | `error=true` + `command not found` | Missing system tool (e.g. `dig`, `nslookup` on Pi). The Pi may not have DNS utilities installed |
+| **Playwright DNS failure** | `error=true` + `net::ERR_NAME_NOT_RESOLVED` | Domain not resolving — DNS not propagated, tunnel not running, or domain misconfigured |
+| **Playwright protocol blocked** | `error=true` + `Access to "file:" URL is blocked` | Agent tried to browse a local file path. Playwright only allows http/https |
+| **Playwright stale ref** | `error=true` + `Ref e* not found in the current page snapshot` | Agent clicked an element reference from an old snapshot without re-snapshotting |
+| **Playwright timeout** | `error=true` + `Timeout *ms exceeded` | Page too slow to render (common on Pi) or font loading stall |
+| **Tool hallucination** | `error=true` + `No such tool available` | Agent invented a tool name that doesn't exist (e.g. missing double underscore in MCP tool name) |
+| **MCP validation error** | `error=true` + `Input validation error` | Agent passed wrong types or missing required fields to an MCP tool |
+| **Cloudflare cert error** | `error=true` + `Could not read certificate` | Cloudflare auth certificate missing or corrupt |
+| **MCP null dereference** | `error=true` + `Cannot read properties of null` | Bug in MCP server code — null check missing |
+
+### Severity: WARNING
+
+These indicate degraded behaviour or potential problems that didn't cause outright failure.
+
+| Pattern | How to detect | Diagnosis |
+|---------|--------------|-----------|
+| **Context overflow** | `[context-overflow]` line | Session used more tokens than the model's context window. The percentage tells you how far over. Above 150% risks truncation and incoherent responses |
+| **Repeated tool errors** | Same tool fails 3+ times in a session | Agent is retrying a broken tool instead of adapting. Check if it's the same error each time (systemic bug) vs different errors (exploratory) |
+| **High cost session** | `total_cost_usd` > $0.50 in a single session result | Unusually expensive — check context overflow and turn count |
+| **Long session** | `duration_ms` > 120000 (2 minutes) | May indicate agent looping or stuck on a task |
+| **Web fetch unavailable** | Tool returns "not available in Phase 0" | Agent tried to use a capability that hasn't been implemented yet |
+| **Rate limit events** | `[unknown-type] type=rate_limit_event` | API rate limit check. `status: "allowed"` is normal. Watch for non-allowed status |
+
+### Severity: INFO (notable but not problems)
+
+| Pattern | How to detect |
+|---------|--------------|
+| **Subagent dispatched** | `[subagent-start]` / `[agent-dispatch]` lines |
+| **Skill expanded** | `[expanded]` line |
+| **UI component rendered** | `[render-component]` / `[browser-viewer]` lines |
+| **Session completed successfully** | `result` JSON with `is_error: false` |
+
+## Diagnosis Heuristics
+
+When multiple errors appear in the same session, look for causal chains:
+
+- **DNS failure → retry loop**: If `ERR_NAME_NOT_RESOLVED` is followed by multiple attempts with different DNS resolution strategies (Bash dig, nslookup, DoH), the agent is trying to diagnose DNS itself. Root cause is always the tunnel or DNS config.
+
+- **Contact-list LIMIT error → retry loop**: If `contact-list error=true` repeats 3+ times in one session, the agent is retrying with the same float parameter. This is a known Neo4j integer bug — the fix is in the MCP server, not the agent's behaviour.
+
+- **Context overflow → degraded behaviour**: If a session has `context-overflow` above 150% AND errors after that point, the overflow likely caused the errors (truncated instructions, lost context).
+
+- **Stale ref → re-snapshot → stale ref**: If `Ref not found` repeats, the agent may not be re-snapshotting between clicks, or the page is dynamically changing.
+
+- **Screenshot timeout cluster**: Multiple `page.screenshot: Timeout` errors indicate Pi performance issues, not agent bugs. The Pi's limited CPU struggles with Playwright rendering.
+
+## Report Format
+
+Structure the report as follows:
+
+```markdown
+# Stream Log Report — [date]
+
+## Summary
+- **Time span**: [first timestamp] → [last timestamp]
+- **Sessions**: [count] total, [errors] with errors, [clean] clean
+- **Total cost**: $[sum of all session costs]
+- **Context overflows**: [count] ([list percentages])
+
+## Errors ([count])
+
+### [Error category name]
+- **Severity**: ERROR
+- **Occurrences**: [count] across [N] sessions
+- **Pattern**: [what happened]
+- **Diagnosis**: [root cause if known, "investigation needed" if not]
+- **Sessions affected**: [session keys or IDs]
+
+[Repeat for each error category]
+
+## Warnings ([count])
+
+### [Warning category name]
+- **Occurrences**: [count]
+- **Pattern**: [what happened]
+- **Impact**: [what this means for the user/system]
+
+[Repeat for each warning category]
+
+## Session Detail
+
+### Session [N] — [sessionKey prefix]
+- **Time**: [start] → [end] ([duration])
+- **Turns**: [count]
+- **Cost**: $[cost]
+- **Result**: [success/error] — [brief outcome from result text]
+- **Issues**: [list of errors/warnings in this session, or "Clean"]
+
+[Repeat for each session]
+
+## Recommendations
+
+[Actionable items derived from the errors and warnings. Group by:
+1. Bugs to fix (code changes needed)
+2. Infrastructure issues (Pi setup, DNS, certificates)
+3. Agent behaviour issues (retry loops, tool misuse)]
+```
+
+Adapt the format to the actual findings — omit empty sections. The goal is a report that a non-technical admin can scan for severity and a developer can use to prioritise fixes.

package/payload/platform/plugins/admin/skills/update-knowledge/skill.md

@@ -0,0 +1,47 @@
+# Update Knowledge
+
+Refresh a public agent's KNOWLEDGE.md from the current graph, scoped to that agent's knowledge configuration.
+
+## When to Use
+
+The admin asks to update, refresh, or regenerate a public agent's knowledge. Examples: "update the knowledge for the sales agent", "refresh the advisor's KNOWLEDGE.md", "rebuild knowledge for all public agents".
+
+## Knowledge Scope
+
+Each public agent's knowledge comes from two complementary sources, both configured in the agent's `config.json`:
+
+**Direct tags** — graph nodes with the agent's slug in their `agents` array.
+
+**Keyword subscriptions** — the agent's `knowledgeKeywords` array. Nodes matching these keywords are included regardless of whether they are directly tagged.
+
+The union of both result sets (deduplicated) forms the agent's knowledge scope.
+
+## Admin vs Runtime Search
+
+This skill runs at admin time, not at runtime. All `memory-search` queries must use admin permissions — do NOT pass `agentSlug` as a parameter. The `agentSlug` parameter applies runtime enforcement logic (restricts graph traversal to tagged nodes only), which is appropriate for the public agent's MCP server but not for admin-time knowledge discovery.
+
+To find directly-tagged nodes: search with the agent's role or topic as the query term (no `agentSlug`), then identify results where the `agents` property contains the target slug.
+
+To find keyword matches: search with each keyword as the query term (no `agentSlug`). Keyword subscriptions exist to capture content beyond the directly-tagged set.
+
+## Constraints
+
+- If the agent has neither direct tags nor keyword subscriptions configured, there is nothing to refresh. Inform the admin: "This agent has no knowledge scope configured. Tag nodes for the agent or add keyword subscriptions in config.json first."
+- If all queries return empty results, do NOT write an empty KNOWLEDGE.md. Warn the admin: "No matching content found for this agent's knowledge scope. KNOWLEDGE.md was not modified." Preserve any existing KNOWLEDGE.md.
+- After writing KNOWLEDGE.md, check the context budget. If the total system prompt (IDENTITY.md + SOUL.md + plugins + KNOWLEDGE.md) exceeds 50% of the model's context window, auto-generate KNOWLEDGE-SUMMARY.md and present it via `document-editor` with `filePath: "agents/{slug}/KNOWLEDGE-SUMMARY.md"` for review.
+- Present the generated KNOWLEDGE.md via `document-editor` with `filePath: "agents/{slug}/KNOWLEDGE.md"` for admin review before finalising.
+- Log the refresh: write a note at the top of KNOWLEDGE.md with the refresh timestamp.
+
+## Querying
+
+Run `memory-search` multiple times with targeted queries to build comprehensive coverage. Do not pass `agentSlug` on any query — all searches use admin permissions.
+
+1. Search with the agent's role or topic as the query term. In the results, identify nodes whose `agents` property contains the target agent's slug — these are the directly-tagged nodes.
+2. For each keyword in the agent's `knowledgeKeywords`, search with that keyword as the query term. These capture content by topic regardless of tagging.
+3. Merge all results, deduplicate by node content, and organise under clear markdown headings by topic.
+
+Categories to cover (where relevant to the agent's role): services, pricing, FAQs, team, policies, products, location/hours, contact info. Skip categories where no matching content exists.
+
+## Bulk Refresh
+
+When asked to refresh all agents, iterate over each public agent directory under `agents/`, read its `config.json`, and run the refresh for each. Present a summary of results.

package/payload/platform/plugins/anthropic/PLUGIN.md

@@ -0,0 +1,38 @@
+---
+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 plugin determines which path to offer based on what the user is trying to do and what they already have configured.
+
+## When to activate
+
+- Prerequisites check detects missing `~/.maxy/.anthropic-api-key`
+- 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
+- User wants to rotate or replace their API key
+
+## 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)
+
+## Skills
+
+| Task | When to use | Reference |
+|------|-------------|-----------|
+| Obtain API key via browser | Missing `~/.maxy/.anthropic-api-key` or user wants to rotate key | `skills/get-api-key.md` |
+
+## References
+
+| Task | When to use | Reference |
+|------|-------------|-----------|
+| Guided setup | User wants help connecting Claude or troubleshooting | `references/setup-guide.md` |
+
+For API key acquisition, use the `skills/get-api-key.md` skill. For troubleshooting and Option A (Claude Pro sign-in), load the reference.

package/payload/platform/plugins/anthropic/references/setup-guide.md

@@ -0,0 +1,114 @@
+# 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: API key
+
+This uses a direct API key from Anthropic's developer console. The user pays per API call.
+
+**During onboarding**, the `skills/get-api-key.md` skill handles this automatically — it opens a browser via Playwright, guides the user through sign-in and key creation, and stores the result via `api-key-store`.
+
+**For key rotation** (user already has a key but wants a new one), activate the same skill. The old key is overwritten.
+
+**Manual fallback** — if the user already has a key and wants to paste it directly:
+
+1. Verify format: starts with `sk-ant-`, at least 90 characters
+2. Store via `api-key-store` tool: `api-key-store({ apiKey: "<the key>" })`
+3. Confirm: "API key stored. Takes effect immediately."
+
+---
+
+## 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/payload/platform/plugins/anthropic/skills/get-api-key.md

@@ -0,0 +1,57 @@
+---
+name: get-api-key
+description: Obtain an Anthropic API key by delegating browser automation to the browser-specialist subagent. Verifies credits are loaded before creating a key to prevent permanently rejected keys.
+---
+
+# Get Anthropic API Key
+
+Obtain an API key from console.anthropic.com on behalf of the user. Browser automation is delegated to `specialists:browser-specialist` — a plugin-defined specialist subagent. All Playwright interaction runs in the specialist's isolated context, keeping the main session lightweight. The user can see the browser via the VNC viewer displayed in the chat.
+
+**Critical ordering rule:** Credits must be confirmed on the account before creating an API key. Keys created on a zero-balance account are permanently rejected by the Anthropic API — even after credits are added later.
+
+## Steps
+
+1. **Show the browser.** Call `render-component` with:
+   - `name: "browser-viewer"`
+   - `data: { title: "Anthropic Console" }`
+
+2. **Dispatch browser-specialist for billing assessment.** Use the Agent tool with `specialists:browser-specialist` as the subagent type. Brief:
+
+   > Navigate to https://console.anthropic.com/settings/billing. Take a screenshot to assess the page. Report what you see: Is there a credit balance shown? Does it say "Buy credits to get started"? Is a sign-in page shown instead? Report the billing status and any dollar amount visible. If sign-in is required, report "SIGN_IN_REQUIRED" and stop.
+
+3. **Handle the billing result.**
+   - If the specialist reports a credit balance greater than $0: proceed to step 6 (create key).
+   - If the specialist reports "SIGN_IN_REQUIRED": proceed to step 4.
+   - If the specialist reports no credits, zero balance, or "Buy credits to get started": proceed to step 5.
+   - If the specialist reports any other error (CAPTCHA, navigation failure, tool unavailable) or the billing status cannot be determined: warn the user that billing status could not be confirmed, and proceed to step 6 (create key). Do not block onboarding on an inconclusive check.
+
+4. **Sign-in required.** Tell the user: "Sign in to your Anthropic account in the browser. You can use Google sign-in or enter your email — Anthropic will send a verification email. Open the email in the same browser (open a new tab) to complete sign-in. If you don't have an account, create one — you will need to add credits before a key can be created." Wait for the user to confirm they have signed in. Then return to step 2 to re-check billing.
+
+5. **No credits — guide the user.** Tell the user: "Your Anthropic account needs credits loaded before I can create an API key. Add credits or enable auto-top-up on the billing page. Let me know when you're done." Wait for confirmation, then dispatch browser-specialist to re-check the billing page (same brief as step 2). If credits are now present, proceed to step 6. If still no credits, repeat this step (maximum 3 attempts). After 3 attempts with no credits detected, tell the user: "Credits still not detected. You can add them at console.anthropic.com/settings/billing and then ask me to create the API key again."
+
+6. **Dispatch browser-specialist for key creation.** Use the Agent tool with `specialists:browser-specialist` as the subagent type. Brief:
+
+   > Navigate to https://console.anthropic.com/settings/keys. Take a screenshot to verify you are on the API Keys page. Create a new API key named "Maxy": find and click the "Create Key" button, fill the key name with "Maxy", submit the form. After creation, look for a string starting with sk-ant- on the page — Anthropic shows the key only once. If found, call api-key-store with the key. Report what happened. If sign-in is required, report "SIGN_IN_REQUIRED" and stop.
+
+7. **Handle the key creation result.**
+   - If the specialist reports the key was stored: proceed to step 9 (verify).
+   - If the specialist reports "SIGN_IN_REQUIRED": this is unexpected since sign-in was handled during the billing check. Tell the user to sign in, wait for confirmation, then retry step 6 once. If it fails again, proceed to step 8 (fallback).
+   - If the specialist reports any other error (CAPTCHA, key not extractable, navigation failure): proceed to step 8 (fallback).
+
+8. **Fallback.** Tell the user: "I could not extract the key automatically. Please copy it from the browser and paste it here in the chat." When the user pastes a key starting with `sk-ant-`, call `api-key-store` with it. Then proceed to step 9.
+
+9. **Verify the key works.** Call the `api-key-verify` MCP tool. Handle each status:
+   - `valid`: Confirm to the user — "API key stored and verified. Your public agent is ready."
+   - `billing`: Credits were confirmed before key creation, so this is unexpected. Tell the user: "The key was stored but credits may not have propagated yet. Please wait a moment." Retry `api-key-verify` once after a brief pause. If still `billing`, tell the user: "Credits are not being detected yet. The key is stored — the public agent will start working once Anthropic recognises the credits on your account."
+   - `auth_error`: The key was rejected. Tell the user: "The stored key was rejected by Anthropic. It may have been copied incorrectly. Let's try again." Return to step 6 (maximum 2 retries — if it fails 3 times total, tell the user to visit console.anthropic.com/settings/keys in their own browser and paste the key manually).
+   - `error`: Could not verify (network or Anthropic issue). Tell the user: "I couldn't verify the key right now — this is likely a temporary issue. The key is stored and should work once the connection is restored."
+
+## Important
+
+- **`render-component` is required before any browser-specialist dispatch.** The browser-viewer component is what makes the VNC browser visible to the user. Without it, automation runs invisibly. Always call `render-component` with `name: "browser-viewer"` and confirm it renders before dispatching a browser-specialist subagent.
+- **Credits before keys.** Never create an API key before confirming that credits are loaded on the account. A key created on a zero-balance account is permanently non-functional.
+- The browser is visible to the user via VNC. They can see everything the specialist does.
+- The user must sign in themselves — the specialist does not fill credentials.
+- For email verification: tell the user to open the verification email in a new tab in the same VNC browser (not on their own device). This keeps the sign-in session in the same browser context.
+- Anthropic shows the API key only once after creation. If the user navigates away before it is captured, they must create a new key.
+- If the browser-specialist is not available (not installed, Agent tool fails), skip the browser-viewer component entirely and tell the user to get a key from console.anthropic.com in their own browser, then paste it in the chat.

package/payload/platform/plugins/business-assistant/PLUGIN.md

@@ -0,0 +1,59 @@
+---
+name: business-assistant
+description: "Business assistant for small businesses. Handles customer enquiries, appointment booking, quote formatting, invoice generation, and daily briefings. Responds instantly, triages by urgency, and never lets a message fall through the cracks."
+metadata: {"taskmaster":{"always":true,"embed":["admin"],"emoji":"💼","pluginKey":"business-assistant","optional":true,"recommended":true}}
+---
+
+# Business Assistant
+
+You are a business assistant for a small business. You handle their customer communications, scheduling, quoting, invoicing, and admin — so they can focus on the work.
+
+## Core Principle: Memory First
+
+**ALWAYS search memory before responding to any message.** Customer details, pricing, schedule, preferences, and business rules all live in memory. Never answer from assumptions — check first.
+
+1. Receive message
+2. Search memory for customer info, schedule, pricing, preferences
+3. Formulate response using what you found
+4. Send response
+5. Update memory with any new information learned
+
+## Identity & Tone
+
+You are an AI-powered business assistant — like a trusted secretary who knows the business. Professional but warm. Match the business owner's tone. Use first names with customers. Keep messages short. Always honest about being an AI when asked.
+
+**Never:** Pretend to be the business owner. Pretend to be human. Commit to a price without approval. Diagnose with certainty. Share the business owner's personal details.
+
+## Core Workflow
+
+Every incoming customer message: identify (new vs existing) → triage (urgent/routine/quick) → gather info → respond or escalate → update memory.
+
+Track status through the pipeline: enquiry → quoted → booked → completed → invoiced → paid.
+
+## Session & Task Continuity
+
+Every conversation is a session. At the start of each session:
+
+1. Call `plugin-read` with `pluginName: "business-assistant"` and `file: "references/task-management.md"` to load the task and session model
+2. Call `session-list` to see recent sessions and open tasks
+3. Call `session-name` with the current `sessionKey` and a short label once the session's purpose is clear
+4. Surface any open tasks to the owner before asking what's new
+
+When the owner asks about sessions, tasks, or what's in progress — use `session-list` and `task-list`.
+
+## Industry Overlays
+
+Load industry-specific references from `overlays/` based on the business type in memory. If no industry is set, ask during the first conversation.
+
+## References
+
+Load the relevant reference when the task requires it:
+
+- **Triage & escalation** → `references/escalation.md` — urgency classification (RED/AMBER/GREEN), customer handoff protocol, voice IVR handling
+- **Scheduling & briefings** → `references/scheduling.md` — booking protocol, geographic clustering, travel time estimation, morning briefings, holiday mode, GPS integration
+- **Quotes** → `references/quoting.md` — photo-to-quote, formatting, follow-up timings
+- **Invoices & payment** → `references/invoicing.md` — HTML invoice creation, PDF generation via `document_to_pdf`, sending, payment chase protocol
+- **Customer records** → `references/crm.md` — contact record management, `contact_lookup`/`contact_update` usage, pipeline tracking, when to create/update records
+- **Document filing** → `references/document-management.md` — dual-scope filing system, naming conventions, folder structure for customer-facing vs internal documents
+- **Task & session management** → `references/task-management.md` — task lifecycle, session naming, cross-session progress tracking
+- **Owner profiling** → `references/profiling.md` — observation triggers, privacy boundaries, when and how to write preferences