@rubytech/create-maxy-code 0.1.0

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/a4-print-documents/SKILL.md

@@ -0,0 +1,241 @@
+---
+name: a4-print-documents
+description: >
+  Constraints for producing print-quality A4 HTML documents intended for PDF output
+  via browser_pdf_save. Use when creating or modifying any HTML document that will be
+  saved as PDF, uses A4 page dimensions, or contains glassmorphism/backdrop-filter effects
+  that must survive print. Trigger phrases: "PDF", "print to PDF", "download PDF",
+  "one-pager", "A4", "brochure", "executive document", "market analysis", or any request
+  to generate a document for print or download.
+---
+
+# A4 Print-Ready HTML Documents
+
+Constraints for producing HTML documents that render correctly when saved as PDF via the personal-assistant's `browser_pdf_save` tool. Every rule exists because violating it caused a visible problem in production documents.
+
+## Rendering path
+
+Generate the HTML document, then delegate to the personal-assistant to save it as PDF using `browser_pdf_save`. The personal-assistant controls Playwright — you compose the delegation brief describing what to render and any pre-render steps (like glassmorphism screenshot capture).
+
+## Glassmorphism does not survive print
+
+`backdrop-filter: blur()`, CSS glassmorphism, and layered transparency effects render as flat, transparent boxes in browser print/PDF output. This is a browser limitation, not a CSS error.
+
+**Required pattern:** Every section using glassmorphism needs a pre-rendered PNG fallback that is hidden on screen and shown only in print.
+
+```css
+.cover-print-img { display: none; }
+
+@media print {
+  .cover > *:not(.cover-print-img) { display: none !important; }
+  .cover-print-img {
+    display: block !important;
+    position: absolute;
+    inset: 0;
+    width: 100%;
+    height: 100%;
+    object-fit: cover;
+  }
+}
+```
+
+```html
+<div class="cover">
+  <img class="cover-print-img" src="cover-print.png" alt="">
+  <!-- live glassmorphism content follows -->
+</div>
+```
+
+This pattern applies to every full-bleed glassmorphism section (cover pages, back pages).
+
+### Capturing the print image
+
+Each glassmorphism section needs its own screenshot — you cannot reuse a print image from a different document or a differently-sized section.
+
+Delegate to the personal-assistant with a brief that includes:
+
+1. **Serve the HTML over HTTP** — `file://` protocol is blocked by Playwright. The specialist should start a local server.
+2. **Set the viewport** to match the element's rendered size. Measure the element's bounding box first, then resize the viewport to `Math.ceil(width) + 1` by `Math.ceil(height) + 1` to eliminate scrollbars.
+3. **Hide UI chrome** (download buttons, navigation overlays) and set `document.body.style.overflow = 'hidden'` to suppress body-level scrollbars.
+4. **Screenshot the specific element** (e.g. `.cover`, `.backpage`) using element-level screenshot — not a full-page or viewport screenshot.
+5. **Save the PNG** alongside the HTML, named for the section it replaces (e.g. `cover-print.png`, `backpage-print.png`).
+6. **Restore** hidden elements and overflow after capture.
+7. **Verify** the saved PNG visually — confirm no scrollbars, no UI chrome, correct dimensions.
+
+After capturing all print images, delegate a second task to save the final PDF via `browser_pdf_save`.
+
+## Page margins, page numbers, and running footers
+
+Use `@page` margin boxes for page numbers and running footers — not `position: fixed` elements.
+
+```css
+@page {
+  margin: 0.6in 0.7in 0.8in;
+  @bottom-center {
+    content: counter(page);
+    font-family: 'Playfair Display', Georgia, serif;
+    font-size: 9pt;
+    color: #8A8A84;
+  }
+}
+
+/* Cover page: zero margins, no page number */
+@page :first {
+  margin: 0;
+  @bottom-center { content: none; }
+}
+
+/* Named page for full-bleed back page */
+@page backpage-full {
+  margin: 0;
+  @bottom-center { content: none; }
+}
+```
+
+Then in `@media print`, the cover needs NO `page:` property — `@page :first` handles it. Only the backpage needs the named page assignment:
+
+```css
+@media print {
+  .cover {
+    width: auto; margin: 0; box-shadow: none; /* reset screen-only properties */
+    min-height: 0;
+    height: 100vh;
+    page-break-after: always;
+    position: relative;
+    overflow: hidden;
+  }
+  .backpage {
+    width: auto; margin: 0; box-shadow: none; /* reset screen-only properties */
+    min-height: 0;
+    height: 100vh;
+    page-break-before: always;
+    position: relative;
+    overflow: hidden;
+    page: backpage-full;
+  }
+}
+```
+
+**Key details:**
+- `@page :first` zeros the margins for the cover — no named page needed on the cover element.
+- Named pages are only needed for non-first full-bleed pages (backpage).
+- `counter(page)` gives automatic page numbering with no JavaScript.
+- No `position: fixed` hacks are needed for repeating headers/footers.
+- If the screen CSS uses `width: 210mm; margin: 20px auto; box-shadow: ...` on the cover/backpage (for the card-on-grey-background look), the print CSS MUST explicitly reset these: `width: auto; margin: 0; box-shadow: none;`. Screen-only layout properties leak into print if not reset. Do NOT use `width: 100vw` or `margin: 0 !important` — just `width: auto; margin: 0`.
+- The print image uses `position: absolute; inset: 0; width: 100%; height: 100%; object-fit: cover;`.
+
+## A4 layout — continuous flow, not fixed-height boxes
+
+Forcing each section into a fixed `height: 297mm` div creates large whitespace gaps when content doesn't fill a full page.
+
+**Correct approach:**
+
+- **Cover page:** `min-height: 100vh` on screen; `height: 100vh; page-break-after: always;` in print.
+- **Content:** Flows naturally. The `@page` margins handle spacing. No fixed-height containers.
+- Use `page-break-inside: avoid` on logical units (cards, tables, callouts, stat groups, timeline items, competitor cards, pullquotes).
+- Use `page-break-before: always` on major section dividers (part breaks).
+- Use `page-break-after: avoid` on headings and section numbers so they don't strand at the bottom of a page.
+- Set `orphans: 3; widows: 3;` on paragraphs to prevent single-line stragglers.
+
+## Dark backgrounds are stripped in print
+
+Browsers strip background colours by default when printing.
+
+**Required:** Add both properties to every dark element in `@media print`:
+
+```css
+@media print {
+  .dark-element {
+    -webkit-print-color-adjust: exact;
+    print-color-adjust: exact;
+  }
+}
+```
+
+## Stripping glassmorphism from content areas
+
+In multi-page documents, strip `backdrop-filter` from content sections (where it won't render correctly anyway) while preserving it on cover/backpage elements that are replaced with print images:
+
+```css
+@media print {
+  /* Strip glass from content */
+  .content *, .content *::before, .content *::after {
+    backdrop-filter: none !important;
+    -webkit-backdrop-filter: none !important;
+    border-radius: 0 !important;
+    box-shadow: none !important;
+  }
+}
+```
+
+## Document structure pattern
+
+Multi-page documents follow this structure:
+
+1. **Cover** — full-bleed, glassmorphism, with print image fallback. Uses `@page :first { margin: 0; }` — NO named page on the element. `page-break-after: always`.
+2. **Table of contents** (optional) — `page-break-after: always` to start content on a fresh page.
+3. **Content sections** — flowing, with part dividers using `page-break-before: always`.
+4. **Back page** — full-bleed CTA/contact page. **Not** an inline footer div — a separate top-level element outside `.body-wrap` with its own named page, print image fallback, and `page-break-before: always`.
+
+**The back page is mandatory for multi-page documents.** An inline CTA footer (a `div` inside flowing content) ends up floating mid-page with whitespace below it. The back page pattern guarantees a clean final page.
+
+```css
+@page backpage-full {
+  margin: 0;
+  @bottom-center { content: none; }
+}
+
+@media print {
+  .backpage {
+    page: backpage-full;
+    min-height: 0; height: 100vh;
+    page-break-before: always;
+    position: relative; overflow: hidden;
+  }
+  .backpage > *:not(.backpage-print-img) { display: none !important; }
+  .backpage-print-img {
+    display: block !important;
+    position: absolute;
+    inset: 0;
+    width: 100%; height: 100%;
+    object-fit: cover;
+  }
+}
+```
+
+```html
+<!-- Outside .body-wrap, after it closes -->
+<div class="backpage">
+  <img class="backpage-print-img" src="backpage-print.png" alt="" style="display:none;">
+  <!-- live backpage content (bg, text, contact info) -->
+</div>
+```
+
+The backpage print image is captured via the same personal-assistant delegation process as the cover — element-level screenshot with UI chrome hidden.
+
+## Single-page documents
+
+For single A4 documents (one-pagers), use fixed dimensions:
+
+```css
+.page {
+  width: 210mm;
+  min-height: 297mm;
+  margin: 0 auto;
+  overflow: hidden;
+}
+
+@page { size: A4; margin: 0; }
+
+@media print {
+  .page {
+    width: 210mm;
+    height: 297mm;
+    page-break-after: always;
+  }
+}
+```
+
+## Document background for multi-page screen viewing
+
+Multi-page documents use a neutral body background (e.g. `body { background: var(--background); }`) on screen. In `@media print`, reset to `body { background: white; }`.

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,53 @@
+---
+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
+- Onboarding step 9 delegates here on first run **only when the operator picked `business-owner` mode**. Personal mode bootstraps a `Person` with `role: "admin-personal"` directly inside step 9 and does NOT invoke this skill.
+- Session-start graph check shows a `LocalBusiness` node with missing data (no hours, no services, empty description)
+- A `memory-write` or `memory-update` returns `no-admin-user` or `no-local-business` — the error message directs the agent here. (For personal-mode accounts, this rejection should not fire because the personal-profile `Person` already satisfies the precondition — if it does fire, the personal-profile node is missing or its `role` is wrong.)
+- Admin asks questions like "update my address", "add our opening hours", "change the phone number"
+
+## First-run path (no LocalBusiness yet)
+
+The `AdminUser` and the operator's personal-profile `Person` are written deterministically at PIN setup time, so this skill no longer creates the AdminUser. When onboarding step 9 invokes this skill in `business-owner` mode, or when a write returns `no-local-business`, create the LocalBusiness:
+
+1. **LocalBusiness.** Ask the user for the business name first — this is the only mandatory property. Call `memory-write` with `labels: ["LocalBusiness"]`, minimal `properties: { name }`, `scope: "shared"`, `relationships: [{ type: "OWNS", direction: "incoming", targetNodeId: "<AdminUser-elementId>" }]`. Find the AdminUser elementId via `memory-search` for the operator's name; the AdminUser already exists from PIN setup.
+2. **Capture the remaining domains** (address, hours, services, FAQs, brand assets) via `memory-update` on the `LocalBusiness` node and `memory-write` for related nodes (`OpeningHoursSpecification`, `Service`, `FAQPage`, `ImageObject`).
+
+Adapt the order if the user provides data in a different sequence — the invariant is: `LocalBusiness` must exist before any subsequent write. Confirm each batch with the user before writing.
+
+## 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. On first run (no `LocalBusiness` yet), skip the search and proceed with the first-run path above.
+- **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.