@rubytech/create-realagent 1.0.406

package/payload/platform/plugins/admin/references/contextual-ui.md

@@ -0,0 +1,107 @@
+# Contextual UI Toolkit
+
+A suite of UI primitives rendered inline in the conversation via `render-component`. Use these when structured interaction improves clarity, reduces ambiguity, or prevents errors — not for every exchange.
+
+## Component Catalogue
+
+| Name | Purpose | Data key fields |
+|------|---------|-----------------|
+| `single-select` | Choose one option from a list | `options[].{value, label, description?}`, `submitMessage?` |
+| `multi-select` | Choose multiple options with checkboxes | `options[].{value, label, description?, badge?, defaultSelected?}`, `submitMessage?`, `skipLabel?` |
+| `confirm` | Approve or reject a consequential action | `title`, `description?`, `items?[].{label, value}`, `confirmMessage?`, `rejectMessage?` |
+| `info-card` | Display structured entity data (read-only) | `title`, `subtitle?`, `fields[].{label, value, type?}`, `actions?[].{label, message, variant}` |
+| `action-list` | List of items with per-item actions | `items[].{id, label, description?, status?, actions[]}`, `doneMessage?` |
+| `form` | Collect 2+ pieces of structured input | `fields[].{name, label, type, description?, placeholder?, required?, options?[].{value, label, description?}}`, `submitMessage?` |
+| `progress` | Multi-step progress tracker (read-only) | `steps[].{label, status, description?}`, `completedMessage?` |
+| `browser-viewer` | VNC iframe for browser automation | `title` |
+| `document-editor` | Inline markdown editor — prose content | `title`, `content` (markdown), `filePath?`, `readOnly?` |
+| `rich-content-editor` | Rich HTML editor — visual/branded content with images | `title`, `content` (HTML fragment), `filePath?`, `readOnly?`, `brandName?`, `brandLogo?` |
+| `grid-editor` | Spreadsheet grid — tabular data editing | `title`, `columns[]`, `rows[][]`, `filePath?`, `brandName?`, `brandLogo?` |
+
+Editors that accept `filePath` display an **Approve** button in the header bar. Omitting `filePath` renders the editor without an approval action — the user can view and edit but cannot submit content for writing. Always include `filePath` when the content requires user approval before being saved to disk.
+
+## Editor Selection
+
+Three editor modes serve different content types. Choose based on what the user is working with:
+
+| Content type | Editor | Examples |
+|---|---|---|
+| Prose — headings, paragraphs, lists | `document-editor` | Knowledge base articles, FAQs, procedures, meeting notes, SOUL files |
+| Visual/branded — HTML with images and layout | `rich-content-editor` | Product cards, blog posts, invoices with logos, marketing materials |
+| Tabular — columns and rows of values | `grid-editor` | Price lists, contact details, inventory, service catalogues |
+
+**Decision rule:** If the content has images or needs branded visual layout → `rich-content-editor`. If the content is a table of values → `grid-editor`. Everything else → `document-editor`.
+
+All three editors support PDF export. Include `brandName` and `brandLogo` (from the business profile in the graph) when the output may be exported as a branded PDF.
+
+## When to Use UI vs. Text
+
+**Use a component when:**
+- The user is choosing from 2+ discrete options → `single-select` or `multi-select`
+- You need approval before a consequential or irreversible action → `confirm`
+- You're presenting a structured entity (contact, task, invoice, status) → `info-card`
+- A list has distinct per-item actions → `action-list`
+- You need 2+ pieces of information at once → `form`
+- A multi-step process benefits from visible progress → `progress`
+
+**Use an editor when:**
+- The user asks to see, review, or edit a document → `document-editor`
+- The user needs visual/branded content (product card, invoice, brochure) → `rich-content-editor`
+- The user asks about tabular data (prices, contacts, inventory) → `grid-editor`
+- "Show me the FAQ" → `document-editor` with the FAQ content
+- "Create a product card for the new range" → `rich-content-editor` with generated HTML
+- "Show me the price list" → `grid-editor` with columns and rows
+
+**Use plain text when:**
+- Simple yes/no — ask in text
+- Open-ended input — ask in text
+- Informational response with no structure — just respond
+- Single piece of information needed — ask in text
+- The interaction is fast and unambiguous without UI
+
+Components add value when they reduce ambiguity, prevent errors, or present structure that text cannot. Not every interaction needs a widget.
+
+## How to Use
+
+Call `render-component` with `name` (component name) and `data` (structured object matching the component's schema). Then wait for the user's response before continuing — the response arrives as a regular message.
+
+### Form field types
+
+The `form` component supports these field types:
+
+| Type | Renders as | Value type | Notes |
+|------|-----------|------------|-------|
+| `text` | Text input | string | Default for short text |
+| `textarea` | Multi-line text | string | For longer input |
+| `select` | Dropdown | string | Requires `options[]` with `{value, label, description?}` — descriptions are appended to the option label |
+| `checkbox` | Toggle checkbox | boolean | Uses the shared Checkbox component. Label appears inline next to the checkbox, not above it |
+| `number` | Number input | string | |
+| `date` | Date input | string | |
+
+All field types accept optional `description` (help text below the label) and `defaultValue` (pre-populated value — used if the user doesn't interact with the field) properties.
+
+For `checkbox` fields, the submitted JSON value is `true` or `false` (boolean), not a string. For all other types, the value is a string.
+
+### Submit message templates
+
+Most components accept a `submitMessage` field that controls the format of the message sent back:
+- `single-select`: `"Selected: {{value}}"` — `{{value}}` and `{{label}}` are replaced
+- `multi-select`: `"Selected: {{values}}"` — `{{values}}` is comma-separated selected values
+- `form`: `"Form submitted: {{json}}"` — `{{json}}` is a JSON string of `{name: value}` pairs. Per-field placeholders `{{fieldName}}` are also supported (e.g. `"model={{model}}, live={{liveMemory}}"`). `{{values}}` is an alias for `{{json}}`
+- `confirm`: `confirmMessage` / `rejectMessage` — literal strings
+- `action-list`: each item action has its own `message` field
+- `info-card`: each action has its own `message` field
+
+When no template is provided, sensible defaults are used.
+
+### Backwards-compatible aliases
+
+These legacy names still work: `output-style` → `single-select`, `thinking-view` → `single-select`, `plugin-selector` → `multi-select`.
+
+## Anti-patterns
+
+- Rendering a `single-select` for a yes/no question — just ask in text
+- Rendering a `form` for a single field — just ask in text
+- Chaining multiple components in one response — render one, wait for the response, then decide if another is needed
+- Using `info-card` for data the user already knows — only show structured display when it adds value
+- Rendering `progress` once and never updating it — progress is for multi-step processes where you re-render with updated step statuses

package/payload/platform/plugins/admin/skills/access-manager/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: access-manager
+description: "Manage per-agent access grants — invite visitors by email or phone, list who has access, revoke or extend access, resend invitations, and set agent access modes (open, gated, paid)."
+---
+
+# Access Manager
+
+Applies when the business owner wants to control who can access a gated or paid public agent.
+
+## When to Activate
+
+- Admin asks to invite someone to a gated agent (by email or phone number)
+- Admin asks who has access, or to list access grants for an agent
+- Admin asks to revoke or extend someone's access
+- Admin asks to set an agent's access mode (open, gated, paid)
+- Admin asks to resend an invitation
+
+## Constraints
+
+- **Admin-scope only.** All AccessGrant nodes must be written with `scope: "admin"`. Credential data must never be visible to public agents.
+- **Agent must exist.** Before any grant operation, verify the target agent directory exists under `agents/` and read its `config.json`.
+- **Confirm before mutating.** Present a `confirm` component before creating grants, revoking access, or changing access modes.
+- **Domain required for email invitations.** Resolve the public hostname via `tunnel-status`. Without a confirmed hostname, magic link URLs cannot be constructed.
+- **Deterministic grant queries.** AccessGrant nodes are not vector-indexed. Query them via `cypher-shell` (password at `~/.maxy/.neo4j-password`), not via `memory-search`.
+
+## Operations
+
+Load `references/operations.md` via `plugin-read` for the AccessGrant data model, grant lifecycle operations, email content requirements, and access list presentation.

package/payload/platform/plugins/admin/skills/access-manager/references/operations.md

@@ -0,0 +1,197 @@
+# Access Grant Operations
+
+Detailed reference for the `access-manager` skill. Covers creating, querying, modifying, and presenting per-agent access grants.
+
+## Prerequisites
+
+Before any grant operation:
+
+- Read the target agent's `config.json` from `agents/{slug}/` to confirm the agent exists, get its `displayName`, and check the current `accessMode`.
+- Read `account.json` to get the `accountId`.
+
+## AccessGrant Data Model
+
+Each grant is an `AccessGrant` node linked to a `Person` node via `(Person)-[:HAS_ACCESS]->(AccessGrant)`.
+
+### Properties
+
+Use these exact property names when creating or updating grants:
+
+| Property | Type | Set on create | Mutable | Notes |
+|---|---|---|---|---|
+| `agentSlug` | string | Yes | No | Target agent's slug |
+| `accountId` | string | Yes | No | From `account.json` |
+| `contactMethod` | `"email"` or `"phone"` | Yes | No | How the invitation was delivered |
+| `contactValue` | string | Yes | No | Email address (lowercase) or phone number (E.164) |
+| `status` | string | Yes | Yes | `"invited"` / `"active"` / `"expired"` / `"revoked"` |
+| `expiresAt` | datetime | Yes | Yes | ISO 8601 datetime. `null` means no expiry |
+| `createdAt` | datetime | Auto | No | Auto-set by `memory-write` |
+| `magicToken` | string | Email only | Yes | Cryptographically random UUID. Nulled after first use |
+| `magicTokenExpiresAt` | datetime | Email only | Yes | 15 minutes from generation |
+| `otpCode` | string | Phone only | Yes | Random 6-digit numeric code |
+| `otpExpiresAt` | datetime | Phone only | Yes | 10 minutes from generation |
+| `passwordHash` | string | No | Yes | scrypt hash. Set by the access gate API when the visitor creates credentials — not by the admin agent |
+| `otpAttempts` | integer | Phone only | Yes | Failed OTP entries. Max 3 before regeneration required |
+| `scope` | `"admin"` | Yes | No | **Mandatory.** Omitting scope exposes grants to public agents |
+
+### Tool Parameters
+
+`memory-write` requires `labels`, `properties`, `accountId`, `scope`, and optionally `relationships`. The `accountId` and `scope` are top-level parameters — not inside `properties`.
+
+`memory-update` requires `nodeId` (element ID from a prior query), `properties` (fields to update), and `accountId`. Always include all three.
+
+### Querying Grants
+
+AccessGrant nodes have no vector index. Query them via `cypher-shell` with the password at `~/.maxy/.neo4j-password`. Do not use `memory-search` for grant lookups.
+
+Example queries (substitute actual values for parameters):
+
+**All grants for an agent:**
+```cypher
+MATCH (p:Person)-[:HAS_ACCESS]->(g:AccessGrant {agentSlug: $slug, accountId: $accountId})
+RETURN elementId(g) AS grantId, p.givenName AS name, g.contactMethod, g.contactValue, g.status, g.expiresAt, g.createdAt
+ORDER BY g.createdAt DESC
+```
+
+**Specific grant by contact:**
+```cypher
+MATCH (p:Person)-[:HAS_ACCESS]->(g:AccessGrant {contactValue: $contact, agentSlug: $slug, accountId: $accountId})
+RETURN elementId(g) AS grantId, elementId(p) AS personId, p.givenName AS name, g.status, g.expiresAt
+```
+
+**Find a Person by email:**
+```cypher
+MATCH (p:Person {email: $email, accountId: $accountId})
+RETURN elementId(p) AS personId, p.givenName AS name
+```
+
+## Invite by Email
+
+**Outcome:** A Person node and AccessGrant node exist in the graph, linked by `HAS_ACCESS`. A magic link email has been sent to the visitor.
+
+### Person node
+
+Search for an existing Person by email using a `cypher-shell` query. If found, reuse its element ID. If not found, create one via `memory-write`:
+
+- Labels: `["Person"]`
+- Properties: `givenName` (if the admin provided a name), `email` (lowercase)
+- `accountId`: from `account.json`
+- `scope`: `"admin"`
+
+### AccessGrant node
+
+Create via `memory-write`:
+
+- Labels: `["AccessGrant"]`
+- Properties: all fields from the data model table. Set `status` to `"invited"`, generate the `magicToken` (random UUID), calculate `magicTokenExpiresAt` (15 minutes from now), and calculate `expiresAt` from the admin's requested duration (or `null` for no expiry).
+- `accountId`: from `account.json`
+- `scope`: `"admin"`
+- Relationships: `[{ type: "HAS_ACCESS", direction: "incoming", targetNodeId: "<person-element-id>" }]`
+
+The `incoming` direction creates `(Person)-[:HAS_ACCESS]->(AccessGrant)`.
+
+### Magic link
+
+Resolve the public hostname via `tunnel-status`. Construct the URL: `https://{hostname}/{agentSlug}?token={magicToken}`
+
+### Email
+
+Send via `email-send`:
+
+- `to` — visitor's email address
+- `subject` — "You've been invited to {displayName}"
+- `body` — plain text version including the magic link URL and access duration
+- `html` — branded email containing:
+  - The agent's display name as a heading
+  - A personal invitation message (from the admin's words, or a sensible default)
+  - A prominent call-to-action button linking to the magic link URL
+  - Access duration ("Your access is valid for 30 days" or "Your access does not expire")
+  - A note that the link expires in 15 minutes
+
+### Confirmation
+
+Before creating the grant and sending the email, present a `confirm` component showing: who is being invited (name, email), which agent, and the access duration.
+
+## Invite by Phone
+
+Same as email invitation with these differences:
+
+- `contactMethod`: `"phone"`
+- `contactValue`: phone number in E.164 format (e.g. `+447700900123`)
+- Generate a random 6-digit `otpCode` instead of a magic token. Set `otpExpiresAt` (10 minutes from now) and `otpAttempts` to `0`. Do not set `magicToken` or `magicTokenExpiresAt`.
+
+### SMS delivery
+
+After creating the grant, deliver the OTP code via SMS. Run this Bash command:
+
+```bash
+curl -s -X POST http://localhost:19200/api/access/send-otp \
+  -H 'Content-Type: application/json' \
+  -d '{"phone": "<contactValue>", "agentSlug": "<agentSlug>"}'
+```
+
+Replace `<contactValue>` with the E.164 phone number and `<agentSlug>` with the target agent's slug.
+
+If the response contains `"success": true`, confirm to the admin that the OTP was sent. If it contains an error, report the error message — common causes: Brevo API key not configured (`~/.maxy/.brevo-api-key` missing), invalid phone number format, or Brevo rate limit reached.
+
+### Brevo SMS setup
+
+Before phone invitations can send SMS, the Brevo API key must be configured. When the admin asks to set up SMS or the first phone invitation fails with a missing key error:
+
+1. Ask the admin for their Brevo API key (from their Brevo account → SMTP & API → API Keys).
+2. Store the key: run `echo "<api-key>" > ~/.maxy/.brevo-api-key && chmod 600 ~/.maxy/.brevo-api-key` via Bash.
+3. Verify delivery by sending a test SMS to the admin's phone. Run the send-otp command above with a test grant, or ask the admin for a phone number and create a temporary test grant.
+
+## List Access Grants
+
+**Outcome:** Admin sees a structured list of all grants for the specified agent.
+
+Query all grants via `cypher-shell`, then present via `render-component` with `action-list`. Each item should include:
+
+- `id` — grant element ID
+- `label` — visitor's display name (fall back to contact value if no name)
+- `description` — "{contactMethod}: {contactValue} -- Expires: {date or 'Never'} -- Since: {createdAt}"
+- `status` — grant status (`invited`, `active`, `expired`, `revoked`)
+- `actions` — "Revoke" and "Extend" buttons. Omit these actions for grants already in `revoked` or `expired` status.
+
+If no grants exist for the agent, say so in text rather than rendering an empty list.
+
+## Revoke Access
+
+**Outcome:** Grant status is `"revoked"`. The visitor is blocked on their next login attempt.
+
+Find the grant via `cypher-shell` to get its element ID. Update via `memory-update` with `properties: { status: "revoked" }`.
+
+Present a `confirm` component before revoking. Explain that active sessions continue until they naturally expire (max 24 hours) — revocation takes effect on the visitor's next login.
+
+## Extend Access
+
+**Outcome:** Grant's `expiresAt` is pushed forward by the requested duration.
+
+Find the grant via `cypher-shell`. Calculate the new `expiresAt` by adding the requested duration to the current `expiresAt` (or to now, if the grant has already expired). Update via `memory-update` with the new `expiresAt` value.
+
+Present a `confirm` component showing the current expiry date and the new expiry date after extension.
+
+## Set Access Mode
+
+**Outcome:** The agent's `config.json` has the updated `accessMode` value.
+
+Read the agent's `config.json`, update the `accessMode` field, and write it back. Valid values:
+
+- `"open"` — anyone with the URL can chat (default, no gate)
+- `"gated"` — only invited visitors with credentials can access
+- `"paid"` — same behaviour as gated (payment integration deferred to a future phase)
+
+Both `gated` and `paid` follow the same code path — the distinction is a semantic label for future use.
+
+Present a `confirm` component before changing, explaining the current mode, the new mode, and what the change means for visitors.
+
+## Resend Invitation
+
+**Outcome:** A fresh magic token or OTP is generated and a new invitation is sent.
+
+Find the existing grant via `cypher-shell`. The grant must be in `invited` or `active` status.
+
+**For email grants:** Generate a new UUID for `magicToken`, set `magicTokenExpiresAt` to 15 minutes from now. Update via `memory-update`. Send the invitation email using the same format as the original invite.
+
+**For phone grants:** Generate a new 6-digit `otpCode`, reset `otpAttempts` to `0`, set `otpExpiresAt` to 10 minutes from now. Update via `memory-update`. Then deliver the new OTP via the SMS delivery command described in the "Invite by Phone" section.

package/payload/platform/plugins/admin/skills/business-profile/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: business-profile
+description: "Populate the business's operational data in the graph — identity, address, opening hours, FAQs, brand assets, and services. Conversational setup that reads existing data first and fills gaps."
+---
+
+# Business Profile Setup
+
+Applies when the business owner wants to set up, complete, or update their business profile — or when a session-start check reveals missing operational data in the graph.
+
+## When to Activate
+
+- Admin asks to set up, edit, or complete their business profile
+- Session-start graph check shows a `LocalBusiness` node with missing data (no hours, no services, empty description)
+- Admin asks questions like "update my address", "add our opening hours", "change the phone number"
+
+## Constraints
+
+- **Schema-first.** Before any write, load `memory/references/schema-base.md` via `plugin-read`. If `businessType` is known on the `LocalBusiness` node, also load the matching vertical schema. Confirm which schemas were loaded.
+- **Read-first.** Search for the existing `LocalBusiness` node and its related entities before asking the user anything. Do not re-ask for data that is already in the graph — reference it and confirm it is still correct.
+- **Confirm before writing.** Present each batch of data back to the user and get explicit confirmation before calling `memory-write` or `memory-update`.
+- **Exact property names.** Use Schema.org camelCase property names exactly as defined in the loaded schema reference. No synonyms, no abbreviations.
+- **No placeholders.** Never write empty strings, "TBD", or "unknown" as property values — they degrade search quality via poor embeddings. If a value is unknown, skip it.
+- **Conversational, not a form.** Adapt to what the user provides. Accept partial input and infer where reasonable (e.g. "9-5 weekdays" means Mon-Fri 09:00-17:00). Allow skipping sections and returning later.
+
+## Data Domains
+
+Six categories of operational data, each mapping to graph nodes defined in `schema-base.md`:
+
+| Domain | Node type | Relationship to LocalBusiness |
+|--------|-----------|-------------------------------|
+| Identity (name, description, telephone, email, url) | `LocalBusiness` properties | — (direct properties) |
+| Address (streetAddress, addressLocality, addressRegion, postalCode, addressCountry) | `LocalBusiness` properties | — (flattened, Phase 0) |
+| Opening hours (per day: dayOfWeek, opens, closes) | `OpeningHoursSpecification` | `HAS_HOURS` |
+| Brand assets (logo, hero image — name, contentUrl, encodingFormat, purpose) | `ImageObject` | `HAS_BRAND_ASSET` |
+| FAQs (question + answer pairs) | `FAQPage` → `Question` | `HAS_FAQ`, then `CONTAINS` |
+| Services (name, description, offers/pricing) | `Service` | `OFFERS` (from LocalBusiness) |
+
+## Writing Nodes
+
+When creating new related nodes (hours, FAQs, assets, services), capture the `LocalBusiness` element ID from the initial search result and use it as `targetNodeId` in the `memory-write` relationships array. For FAQ questions, first create the `FAQPage` node, then create `Question` nodes related to the `FAQPage` via `CONTAINS`.
+
+When updating existing data (changing a phone number, correcting an address), use `memory-update` with the node's element ID from the search result.

package/payload/platform/plugins/admin/skills/datetime/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: datetime
+description: >
+  Timezone queries: current time in any city or timezone, time conversion between
+  zones, UTC offset, and DST status. Trigger phrases: "what time is it in",
+  "convert time", "timezone", "time difference", "DST".
+---
+
+# Datetime & Timezone Queries
+
+Answer timezone-related questions using the server's `<datetime>` context and Node.js `Intl.DateTimeFormat` for cross-zone lookups.
+
+## When to Activate
+
+- User asks for the current time in a named city or timezone
+- User asks to convert a time between timezones
+- User asks about UTC offset, time difference, or DST status for a location
+- User asks "what time is it?" with a location qualifier
+
+For simple "what time is it?" without a location, answer directly from the `<datetime>` block in the system prompt — no tool use needed.
+
+## Behaviour
+
+Use Bash to run a Node.js one-liner with `Intl.DateTimeFormat`. The IANA timezone database is built into Node.js — no external packages are required.
+
+### Current time in a timezone
+
+```bash
+node -e "console.log(new Intl.DateTimeFormat('en-GB', { weekday:'long', year:'numeric', month:'long', day:'numeric', hour:'2-digit', minute:'2-digit', second:'2-digit', timeZone:'IANA_TZ', timeZoneName:'longOffset' }).format(new Date()))"
+```
+
+Replace `IANA_TZ` with the target timezone identifier (e.g., `America/New_York`, `Asia/Tokyo`, `Europe/Berlin`).
+
+### Time conversion
+
+To convert a specific time from one zone to another, construct a `Date` object for the source time and format it in the target zone:
+
+```bash
+node -e "
+const d = new Date('ISO_DATETIME');
+const fmt = (tz) => new Intl.DateTimeFormat('en-GB', { weekday:'long', year:'numeric', month:'long', day:'numeric', hour:'2-digit', minute:'2-digit', timeZone:tz, timeZoneName:'short' }).format(d);
+console.log(fmt('SOURCE_TZ'));
+console.log(fmt('TARGET_TZ'));
+"
+```
+
+### DST and offset info
+
+```bash
+node -e "
+const now = new Date();
+const opts = { timeZone:'IANA_TZ', timeZoneName:'longOffset' };
+const parts = new Intl.DateTimeFormat('en-GB', opts).formatToParts(now);
+const offset = parts.find(p => p.type === 'timeZoneName')?.value ?? 'unknown';
+// Check DST by comparing Jan and Jul offsets
+const jan = new Date(now.getFullYear(), 0, 1);
+const jul = new Date(now.getFullYear(), 6, 1);
+const janOff = new Intl.DateTimeFormat('en-GB', opts).formatToParts(jan).find(p => p.type === 'timeZoneName')?.value;
+const julOff = new Intl.DateTimeFormat('en-GB', opts).formatToParts(jul).find(p => p.type === 'timeZoneName')?.value;
+const dstActive = janOff !== julOff;
+const inDst = dstActive && offset !== janOff;
+console.log('Current offset:', offset);
+console.log('DST observed:', dstActive);
+console.log('Currently in DST:', inDst);
+"
+```
+
+## Common City-to-Timezone Mapping
+
+When the user names a city, map it to the IANA identifier:
+- London → `Europe/London`
+- New York → `America/New_York`
+- Los Angeles → `America/Los_Angeles`
+- Tokyo → `Asia/Tokyo`
+- Sydney → `Australia/Sydney`
+- Dubai → `Asia/Dubai`
+- Mumbai / Delhi → `Asia/Kolkata`
+- Berlin / Paris → `Europe/Berlin` / `Europe/Paris`
+- Singapore → `Asia/Singapore`
+- Hong Kong → `Asia/Hong_Kong`
+
+For less common cities, use Bash to search the IANA database:
+```bash
+node -e "console.log(Intl.supportedValuesOf('timeZone').filter(z => z.toLowerCase().includes('SEARCH_TERM'.toLowerCase())).join('\n'))"
+```
+
+## Boundaries
+
+- Answers timezone questions only — not scheduling, reminders, or alarms.
+- Uses the server's system clock. If the server clock is wrong, answers will be wrong.
+- Historical timezone data (e.g., "what time was it in Tokyo on 15 March 1990?") depends on the Node.js ICU dataset and may be inaccurate for dates before 1970.

package/payload/platform/plugins/admin/skills/onboarding/skill.md

@@ -0,0 +1,136 @@
+# Onboarding
+
+Guided first-run setup for new Maxy installations. Runs automatically at every session start when `onboarding-get` returns `currentStep` less than 7. Resume from the first incomplete step — skip any step whose number is at or below `currentStep`.
+
+After completing each step, persist progress immediately by calling `onboarding-complete-step` with the step number just completed. This ensures that if the session ends, the next session resumes from the right place.
+
+Every user selection and every document presentation in onboarding renders through `render-component` — never as markdown text, bullet lists, or inline chat content. Selections use `single-select` or `multi-select`; file content (SOUL, KNOWLEDGE, config) uses `document-editor`. Describing options in prose or pasting file content into a chat message bypasses the UI and the user's ability to review and edit before saving. Never use directional words ("above", "below") when referring to a rendered component — just name it or refer to "the browser", "the editor", etc. The `document-editor` component renders one file at a time — never call `render-component` with `document-editor` twice in the same turn. Present one file, wait for the user's approval or edit, then present the next.
+
+## Step 1 — Plugin selection
+
+*(skip if `currentStep` >= 1)*
+
+Call `render-component` to surface a checkbox UI — do not list plugins as markdown. Pass `name: "multi-select"` and data as an object with `selectAll: true`, `submitMessage: "Install the following plugins: {{values}}"`, `skipLabel: "Skip"`, `skipMessage: "Skip plugin installation"`, and `options` as a single array containing every item below (core, then optional Maxy, then Claude Official — all in one array):
+
+`{ value: "admin", label: "admin", description: "Platform management — system status, account settings, logs, session control.", badge: "Core", group: "Core — always active", locked: true, defaultSelected: true }`,
+`{ value: "memory", label: "memory", description: "Graph memory — search, write, reindex, and ingest knowledge.", badge: "Core", group: "Core — always active", locked: true, defaultSelected: true }`,
+`{ value: "maxy-guide", label: "maxy-guide", description: "User guide and platform documentation — loaded on demand.", badge: "Core", group: "Core — always active", locked: true, defaultSelected: true }`,
+`{ value: "cloudflare", label: "cloudflare", description: "Cloudflare Tunnel — expose your assistant publicly via a custom domain.", badge: "Core", group: "Core — always active", locked: true, defaultSelected: true }`,
+`{ value: "anthropic", label: "anthropic", description: "Claude connection — API key acquisition and configuration.", badge: "Core", group: "Core — always active", locked: true, defaultSelected: true }`,
+`{ value: "deep-research", label: "deep-research", description: "Structured multi-source research — query decomposition, source evaluation, citation formatting.", badge: "Core", group: "Core — always active", locked: true, defaultSelected: true }`,
+`{ value: "business-assistant", label: "business-assistant", description: "Customer enquiries, scheduling, quoting, invoicing, daily briefings.", badge: "Recommended", group: "Maxy", defaultSelected: true }`,
+`{ value: "sales", label: "sales", description: "Buying signal detection, closing techniques, objection handling.", badge: "Recommended", group: "Maxy", defaultSelected: true }`,
+`{ value: "scheduling", label: "scheduling", description: "Calendar and scheduling — events, appointments, recurring triggers.", badge: "Recommended", group: "Maxy", defaultSelected: true }`,
+`{ value: "tasks", label: "tasks", description: "Graph-backed task lifecycle — create, update, list, relate, complete.", badge: "Recommended", group: "Maxy", defaultSelected: true }`,
+`{ value: "email", label: "email", description: "Agent email account — setup, read, send, search.", badge: "Recommended", group: "Maxy", defaultSelected: true }`,
+`{ value: "contacts", label: "contacts", description: "CRM contact management — create, lookup, update, list.", badge: "Recommended", group: "Maxy", defaultSelected: true }`,
+`{ value: "workflows", label: "workflows", description: "Persistent named workflows — reusable instruction sets.", badge: "Recommended", group: "Maxy", defaultSelected: true }`,
+`{ value: "documents", label: "documents", description: "Document management and PDF generation.", badge: "Recommended", group: "Maxy", defaultSelected: true }`,
+`{ value: "telegram", label: "telegram", description: "Telegram bot setup — BotFather, admin and public channels.", group: "Maxy" }`,
+`{ value: "waitlist", label: "waitlist", description: "Waitlist lifecycle — extract sign-ups, review, schedule automation.", group: "Maxy" }`,
+`{ value: "stripe", label: "stripe", description: "Live access to payment and business data.", group: "Claude Official" }`,
+`{ value: "zapier", label: "zapier", description: "Cross-app automation — connect thousands of apps.", group: "Claude Official" }`
+
+Wait for the user's component submission before continuing. Their response will either list the plugins they selected or indicate they skipped. The submission contains only non-locked (optional) plugin names — core plugins are always active and not included in the submission.
+
+- For each selected **Claude Official plugin**, run: `claude plugin install <name>@claude-plugins-official`
+- For each selected **Maxy plugin**, read the current `account.json` via `account-manage`, add the plugin name to the `enabledPlugins` array (create the array if absent), and write back via `Edit`. Use the `value` field (not `label`) as the plugin name — e.g., `docs` not `maxy-guide`. This activates the plugin's behaviour and MCP server from the next session.
+
+After installing/enabling (or skipping), call `onboarding-complete-step` with step 1.
+
+If any Maxy plugins were enabled in this step, call `session-reset` immediately after completing step 1. Maxy plugin MCP servers only load when a new subprocess spawns — the current session cannot access them. After the reset, the new session calls `onboarding-get` (returning `currentStep = 2`) and resumes from Step 2 with all newly enabled plugins available. If no Maxy plugins were enabled (user skipped or selected only Claude Official plugins), proceed directly to Step 2 — no reset needed.
+
+## Step 2 — Anthropic API key
+
+*(skip if `currentStep` >= 2)*
+
+The public-facing agent uses the Anthropic API directly. Without a key, visitors cannot chat with the business. Check if the key exists: run `test -f ~/.maxy/.anthropic-api-key && echo "exists" || echo "missing"` via Bash.
+
+If missing, use `plugin-read` to load `anthropic/skills/get-api-key.md` and follow its instructions. The skill delegates browser automation to `specialists:browser-specialist` — 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 rendered in the chat.
+
+If the key already exists, skip this step.
+
+After the key is stored (or was already present), call `onboarding-complete-step` with step 2.
+
+## Step 3 — Cloudflare Tunnel
+
+*(skip if `currentStep` >= 3)*
+
+Remote access via a custom domain. Without this, the platform is only reachable on the local network. Check `tunnel-status` — if the tunnel is already running, skip this step.
+
+If the tunnel is not configured or `tunnel-status` shows a CRITICAL nameserver warning, ask the user: "Would you like to set up remote access now? This connects your platform to a custom domain so you and your customers can reach it from anywhere. You will need a Cloudflare account and a domain. If you do not have these yet, we will set them up together now."
+
+If the user wants to proceed: call `render-component` with `name: "browser-viewer"` and `data: { title: "Cloudflare" }` FIRST, then use `plugin-read` to load `cloudflare/skills/setup-tunnel.md` and follow its instructions exactly. The entire Cloudflare setup — sign-in, domain addition, nameserver changes at the registrar — happens in the VNC browser via `specialists:browser-specialist`. The user never leaves the chat. Do not improvise an alternative flow. Do not tell the user to go to a website themselves.
+
+If the user skips, let them know they can set up Cloudflare at any time by asking.
+
+After the tunnel is set up (or the user skips), call `onboarding-complete-step` with step 3.
+
+## Step 4 — Specialist verification
+
+*(skip if `currentStep` >= 4)*
+
+Specialists are pre-installed by the platform. Read `agents/admin/AGENTS.md` to get the list of installed specialists. For each specialist, also read `specialists/agents/{name}.md` and extract the `summary` field from its YAML frontmatter — this is the user-facing description. Present each specialist to the user using its name and `summary`. Do not use the `description` field for user display — it contains delegation routing information not intended for users. If AGENTS.md is empty, fall back to scanning: use `Bash` to list `specialists/agents/*.md`, read each file's frontmatter to extract name, summary, and description, and append one line per specialist to `agents/admin/AGENTS.md`: `- **specialists:{name}**: {one-line delegation rule — when to dispatch}`.
+
+Use `Bash` to list `$PLATFORM_ROOT/templates/specialists/agents/` for any `.md` files whose description contains "Phase 1" or "not yet available". Mention these as coming soon.
+
+After verifying, call `onboarding-complete-step` with step 4.
+
+## Step 5 — Output style
+
+*(skip if `currentStep` >= 5)*
+
+Call `render-component` to surface a radio selector UI. Pass `name: "single-select"` and data with `submitMessage: "Set output style to {{value}}"` and `options` as an array:
+
+- `{ value: "default", label: "Default", description: "Efficient and task-oriented — concise responses without extra explanation." }`
+- `{ value: "explanatory", label: "Explanatory", description: "Adds educational insights between steps, great for learning." }`
+
+Wait for the user's component submission before continuing. Their response will specify the chosen style. Call `account-update` with field `outputStyle` and the chosen value. Call `onboarding-complete-step` with step 5.
+
+## Step 6 — Thinking view
+
+*(skip if `currentStep` >= 6)*
+
+Call `render-component` to surface a radio selector UI. Pass `name: "single-select"` and data with `submitMessage: "Set thinking view to {{value}}"` and `options` as an array:
+
+- `{ value: "default", label: "Thinking visible", description: "Shows reasoning expanded, collapses tool details." }`
+- `{ value: "expanded", label: "Everything visible", description: "Expands all reasoning and tool details." }`
+- `{ value: "collapsed", label: "Responses only", description: "Collapses all reasoning and tool details." }`
+
+Wait for the user's component submission before continuing. Their response will specify the chosen view. Call `account-update` with field `thinkingView` and the chosen value. Call `onboarding-complete-step` with step 6.
+
+After step 6, let the user know that everything configured during onboarding — plugins, the API key, Cloudflare, specialists, output style, and thinking view — can be changed at any time through conversation.
+
+## Step 7 — Business personalisation
+
+*(skip if `currentStep` >= 7)*
+
+Configure the default public agent and write the agent personality files. All paths are relative to the account directory (the working directory).
+
+First, check whether personalisation is already complete: read `agents/admin/SOUL.md`, then scan the `agents/` directory for any non-admin subdirectory containing both `SOUL.md` (with actual business content, not just the `# Soul` header) and `config.json`. If the admin SOUL and at least one public agent are both personalised, call `onboarding-complete-step` with step 7 and skip to business onboarding — the personalisation is already in place.
+
+**Public agent identity.** Before configuring the model or plugins, establish who the public agent is. Ask the user for:
+
+- A **display name** for the agent — the name visitors will see (e.g. "Ruby", "Estate Assistant", "Kai"). This is the agent's identity, not the business name.
+- A **role description** — what the agent does in one or two sentences (e.g. "Handles property enquiries and books viewings", "Answers customer questions about our menu and takes reservations").
+
+Both fields are required. If the user provides an empty response for either, explain why it matters and ask again. The display name becomes the `displayName` in the agent's config. The role description is used when drafting the agent's SOUL.md personality later in this step.
+
+**Admin personality.** If the admin SOUL file (`agents/admin/SOUL.md`) is empty or missing business content, the user must provide personalisation input through conversation. Product knowledge in the graph is background context — not a substitute for the user describing their business identity and preferences. Ask the user about:
+
+- Their business: who the customers are, current stage, and any context beyond what the role description already covers
+- Tone and personality: how the agents should sound (formal, casual, warm, blunt, etc.), language preferences
+
+Use `memory-search` to check for any business context already in the graph — reference it to avoid re-asking what's already known, but still confirm with the user. The conversation shapes the personality; the graph fills in factual detail.
+
+SOUL is personality — not a product brochure. Factual business data belongs in the graph. SOUL contains only what the agent needs to *be itself*: the business name, your role within it, tone, language preferences, and working style.
+
+Present the admin SOUL via `render-component` with `name: "document-editor"` and `data: { title: "Admin agent personality", content: <the markdown>, filePath: "agents/admin/SOUL.md" }`. The user must approve (or edit and approve) the content before any Write call. When the user approves or edits, you receive `{ action: "approve", content: "<markdown>", filePath: "<path>" }` or `{ action: "save", content: "<markdown>", filePath: "<path>" }`. Write the `content` to the specified `filePath` using the Write tool.
+
+**Public agent creation.** Load the public agent management skill via `plugin-read` from `admin/skills/public-agent-manager/skill.md`. Pass the display name and role description gathered above as context. The skill handles the full creation workflow — model selection, plugin selection, directory setup, SOUL.md drafting, knowledge strategy, KNOWLEDGE.md population, config.json generation, and context budget check — including user approval for all files via document-editor components.
+
+After the skill workflow completes, call `onboarding-complete-step` with step 7.
+
+**Document ingestion.** If the user uploaded any documents during Step 7 (or earlier in the session), dispatch the `document-specialist` subagent to ingest them AFTER calling `onboarding-complete-step` — not before. Use the Agent tool with `run_in_background: true`. The critical path (SOUL files, config.json, step completion) must not depend on document ingestion succeeding. If no documents were uploaded, skip this step.
+
+Continue with normal business onboarding.