@rubytech/create-maxy-code 0.1.0

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

@@ -0,0 +1,277 @@
+# Public Agent Manager
+
+Create, edit, clone, list, preview, and delete public agents. Each public agent is a self-contained directory under `agents/` with its own identity, personality, knowledge, model, and selected plugins.
+
+## Agent Directory Structure
+
+Each agent lives at `{accountDir}/agents/{slug}/`:
+
+| File | Purpose | Required |
+|------|---------|----------|
+| `config.json` | Model, selected plugins, display name, status, image identity | Yes |
+| `IDENTITY.md` | Boundaries, behavioural rules | Yes |
+| `SOUL.md` | Personality only — tone, voice, warmth, greeting style | Yes |
+| `KNOWLEDGE.md` | Domain facts from the graph — pricing, FAQs, services | No |
+| `KNOWLEDGE-SUMMARY.md` | Auto-generated summary when KNOWLEDGE.md exceeds context budget | No |
+| `assets/` | Per-agent images (logo, avatar, icon) | No |
+
+## Slug Rules
+
+- Lowercase a-z, 0-9, hyphens only
+- 3-50 characters, must start with a letter
+- Reserved (rejected): `admin`, `api`, `assets`, `agent-assets`, `brand`, `bot`, `privacy`
+- `public` is the conventional default slug, but public agents are optional — the platform operates without any
+
+## config.json
+
+```json
+{
+  "slug": "sales",
+  "displayName": "Sales Agent",
+  "model": "claude-haiku-4-5",
+  "plugins": ["sales"],
+  "status": "active",
+  "liveMemory": false,
+  "knowledgeKeywords": [],
+  "image": "/agent-assets/sales/agent-image.png",
+  "imageShape": "circle",
+  "showAgentName": true
+}
+```
+
+### liveMemory
+
+When `true`, the platform queries the knowledge graph at runtime per message and appends live results alongside baked KNOWLEDGE.md. When `false` (default), the agent uses only the static KNOWLEDGE.md snapshot.
+
+Present during creation and editing as a yes/no choice. Explain the trade-off: live memory adds a small latency per message (~1-2s) but keeps the agent current with graph changes. For agents with static knowledge (pricing, FAQs), leave off. For agents that need to reflect recent graph updates (dynamic catalogues, changing availability), enable it.
+
+### knowledgeKeywords
+
+Topic keywords the agent subscribes to. When the graph is searched for this agent (at runtime via `liveMemory` or during a `update-knowledge` refresh), nodes matching these keywords are included automatically — even if they are not directly tagged for the agent.
+
+Maximum 5 keywords. Present during creation as a free-text input. Examples: `["climate science", "sustainability"]`, `["pricing", "services"]`.
+
+### Agent Image
+
+An optional image (avatar, icon, or logo) displayed in the public chat header instead of the account-level brand logo. Managed via the `agent-image` MCP tool.
+
+- `image` — URL path to the image (e.g. `/agent-assets/sales/agent-image.png`). Set automatically by the `agent-image` tool.
+- `imageShape` — `"circle"` for avatars and icons, `"rounded"` for logos. Controls the CSS border-radius applied to the image in the chat header.
+- `showAgentName` — `true`: chat header displays `displayName`; `false` (default): header shows the business name from branding data; `"none"`: no name displayed at all (logo-only header, useful when the logo already contains the brand name).
+
+**Fallback chain:** agent image → account brand logo → platform default icon. When no image is configured, the existing brand logo behaviour is preserved.
+
+During creation (Step 7) and editing, offer image upload when the user has an image ready. Use the `agent-image` tool with `action: "set"`, providing the file path and the appropriate shape. If the user wants the agent's name shown in the header, set `showAgentName: true` in config.json.
+
+### Knowledge Tagging
+
+Nodes in the graph can be directly tagged for a specific agent by adding the agent's slug to the node's `agents` array property. This is the explicit tagging mode — the admin decides exactly which nodes an agent can see. Direct tagging and keyword subscriptions (`knowledgeKeywords`) are independent routing mechanisms — each is configured and approved separately, and neither implies the other.
+
+To tag nodes: use `memory-update` to add the agent's slug to a node's `agents` array (read current array first via `memory-search` to avoid overwriting existing slugs). To untag: read the current `agents` array, remove the slug, and update. To see what's tagged for an agent: search with `memory-search` (no `agentSlug` param) and identify results whose `agents` property contains the target slug.
+
+### Model Options
+
+Present as a `select` field within the agent configuration `form` during creation:
+
+| Model | ID | Suitability | Cost |
+|-------|-----|------------|------|
+| Haiku | `claude-haiku-4-5` | Fast, cost-effective. FAQ, routing, high-volume. | Low |
+| Sonnet | `claude-sonnet-4-6` | Balanced. Nuanced conversation, qualification, support. | Standard |
+| Opus | `claude-opus-4-7` | Maximum intelligence. Complex sales, consultative selling. | Premium |
+
+### Plugin Selection
+
+Present available plugins as a `multi-select` component. Selected plugin names are stored in `config.json`. The platform filters embedded plugins per-agent at runtime — only plugins whose `metadata.platform.embed` includes `"public"` are actually embedded.
+
+Only present plugins from the curated list below. Before presenting, verify each plugin's directory exists under `$PLATFORM_ROOT/plugins/` (premium plugins are only available when delivered). Omit any plugin whose directory is absent.
+
+**Core (always available):**
+
+| Plugin | Description |
+|--------|-------------|
+| `sales` | Buying signal detection, closing techniques, objection handling |
+| `docs` | User guide and platform documentation |
+
+**Premium — Real Agency (only when delivered):**
+
+| Plugin | Description |
+|--------|-------------|
+| `buyers` | Buyer enquiry handling and educational guides |
+| `estate-coaching` | Agent coaching and performance development |
+| `estate-onboarding` | Client onboarding workflows |
+| `estate-sales` | Real estate sales methodology |
+| `estate-teaching` | Training and educational content |
+
+## SOUL.md Scope Enforcement
+
+SOUL.md is strictly personality. When the user provides content for SOUL.md, route non-personality content to the correct file:
+
+- **Facts, pricing, services, FAQs** → KNOWLEDGE.md
+- **Engagement strategy, qualification flows, component usage** → handled by selected plugins
+- **Boundaries, tool rules, procedural instructions** → IDENTITY.md
+
+SOUL.md answers "what does this agent feel like to talk to?" — tone, warmth, formality, humour, greeting personality. SOUL.md must not restate constraints from IDENTITY.md. When user-provided content could belong to either file, apply this test: "does this restrict what the agent does?" → IDENTITY.md. "Does this describe how the agent sounds?" → SOUL.md. If content does both (e.g. "always respond politely"), route to SOUL — the constraint is a consequence of tone, not an operational boundary. Present SOUL.md via `document-editor` for the user to review and approve. Follow the document-editor encoding constraint in IDENTITY.md when generating content.
+
+## KNOWLEDGE.md Population
+
+KNOWLEDGE.md is the public agent's only source of factual knowledge. Public agents run via the direct Anthropic API with no runtime access to the graph — no `memory-search`, no filesystem, no MCP tools. Once KNOWLEDGE.md exists, the server skips runtime memory-search entirely. Every gap in KNOWLEDGE.md is a question the public agent cannot answer.
+
+All `memory-search` queries for knowledge population use admin permissions — do not pass `agentSlug`. The `agentSlug` parameter is a runtime enforcement mechanism for the public agent's MCP server, not an admin-time discovery tool. At creation time, the agent may have zero tagged nodes — searching with `agentSlug` would return nothing.
+
+Query `memory-search` multiple times with targeted terms across all categories relevant to the agent's role. A single broad query will miss knowledge stored under specific labels or entity types. Common categories:
+
+- Services, pricing, availability
+- FAQs
+- Team / people (public-facing details only)
+- Policies (returns, cancellations, terms)
+- Products / catalogue
+- Location, hours, contact info
+
+For each category relevant to the agent, confirm that results were returned or that the graph genuinely has no data for that category. Write results as structured markdown under clear headings.
+
+After writing KNOWLEDGE.md, check the token budget. If the total system prompt exceeds 50% of the model's context window, summarise KNOWLEDGE.md and write the summary to `KNOWLEDGE-SUMMARY.md`. Present the summary to the user for review.
+
+## Context Budget
+
+The system prompt must leave room for conversation. After assembling all files, estimate the total token count. Present the breakdown to the user:
+
+```
+IDENTITY.md:     800 tokens
+SOUL.md:         400 tokens
+sales plugin:  2,100 tokens
+KNOWLEDGE.md:  8,200 tokens
+─────────────────────────
+Total:        11,500 / 40,000 (29%)
+```
+
+Warn if total exceeds 50% of the model's context window.
+
+## Operations
+
+### Create from Template
+
+When template context is provided (a path to a template directory containing `template.json`, `IDENTITY.md`, and `SOUL.md`), the Create operation pre-populates its steps from the template. The user reviews and approves every file — the template is a starting point, not an automatic deployment.
+
+Read the template's `template.json` and seed files. If `template.json` is unreadable or missing required fields (`suggestedSlug`, `displayName`), report the error and fall back to the standard Create flow.
+
+The following Create steps are modified when a template is provided:
+
+- **Step 1** — use `suggestedSlug` from `template.json` as the initial slug. If an agent already exists at that slug, ask the user to choose a different name.
+- **Step 2** — skip. The agent name and role come from `template.json` `displayName` and `description`.
+- **Step 3** — pre-select the plugins listed in `template.json` `plugins` array. Only plugins that appear in the curated public-eligible list (see Plugin Selection above) can be pre-selected. If any template plugin is not available (not delivered, not enabled, or not marked for public embed), note which ones are missing and let the user adjust the selection.
+- **Step 5** — present the template's `IDENTITY.md` content via `document-editor` instead of drafting from a role description. The user can edit before approving.
+- **Step 6** — present the template's `SOUL.md` content via `document-editor` instead of drafting from conversation. The user can edit before approving.
+- **Step 7** — pre-populate form defaults: `model` from `template.json` (or `claude-haiku-4-5` if absent), `liveMemory` from `template.json` (or `false`), `knowledgeKeywords` from `template.json` (or empty).
+
+All other steps (4, 8-12) proceed identically — knowledge discovery, direct tagging, KNOWLEDGE.md generation, config write, budget check, and confirmation are unchanged.
+
+After creation, no template metadata persists in the agent's files. The resulting agent is indistinguishable from one created manually. The user owns it completely.
+
+### Create
+
+1. **Pre-creation check** — verify the target directory (`agents/{slug}/`) does not exist or is empty before proceeding. If remnant files exist from a prior incomplete deletion, flag the issue to the user: show what files remain and offer to clean them up before starting fresh. Do not silently inherit stale files — a leftover `config.json` from a previous agent would bypass the creation gate.
+2. Ask for the agent's name (becomes the slug) and role description
+3. Present available plugins (multi-select)
+4. **Knowledge discovery** — search the graph with admin permissions (no `agentSlug` — the agent doesn't exist yet) to find available knowledge. Present available content grouped by category for the user to select.
+5. Present `IDENTITY.md` via document-editor with `filePath: "agents/{slug}/IDENTITY.md"` (draft from role description). Write on approval.
+6. Present `SOUL.md` via document-editor with `filePath: "agents/{slug}/SOUL.md"` (draft personality from user conversation). Write on approval.
+7. Present agent configuration via a single `form` component with these fields:
+   - `liveMemory` (`checkbox`): label "Live memory", description explaining the trade-off — live memory adds ~1-2s latency per message but keeps the agent current with graph changes; leave off for static knowledge (pricing, FAQs), enable for dynamic content
+   - `knowledgeKeywords` (`text`): label "Knowledge keywords (max 5, comma-separated)", placeholder with examples relevant to the agent's role
+   - `model` (`select`): label "Model", options with descriptions:
+     - `claude-haiku-4-5` — "Haiku — Fast, cost-effective. FAQ, routing, high-volume."
+     - `claude-sonnet-4-6` — "Sonnet — Balanced. Nuanced conversation, qualification, support."
+     - `claude-opus-4-7` — "Opus — Maximum intelligence. Complex sales, consultative selling."
+   - `showAgentName` (`select`): label "Chat header title", options: `false` — "Business name (default)", `true` — "Agent display name", `"none"` — "None (logo only)"
+   The `model` field should have a `defaultValue` of `"claude-haiku-4-5"`.
+   Wait for the user's response before proceeding.
+   After the form is submitted, ask the user if they have an image (avatar, icon, or logo) for the agent. If yes, ask the user to provide the file and select the shape (circle for avatars/icons, rounded for logos), then use the `agent-image` tool to upload it.
+8. **Direct slug tagging (optional, gated)** — keyword subscriptions (configured in Step 7) and direct slug tagging are independent routing mechanisms. Keyword subscriptions route content by topic — any matching node is visible, now or in the future. Direct slug tagging routes specific nodes by identity — only explicitly tagged nodes are visible via the slug search path. Neither implies the other.
+
+   Ask the user whether any specific knowledge nodes should be tagged with this agent's slug. Explain that direct tagging makes specific nodes always visible to this agent regardless of keyword matches, and is useful for content that doesn't match any keyword but should still be available. If keyword subscriptions already cover the desired content, tagging is unnecessary.
+
+   - If the user approves: present the knowledge discovery results from Step 4 for selection, then tag selected nodes (add slug to `agents` array via `memory-update`). Read each node's current `agents` array first to avoid overwriting existing slugs.
+   - If the user declines: skip tagging entirely. Do not tag nodes without explicit approval.
+9. **KNOWLEDGE.md generation** — populate from the now-tagged set plus keyword matches using the `update-knowledge` skill workflow
+10. Write `config.json` with selected model, plugins, status "active", `liveMemory`, and `knowledgeKeywords`. This is the last gated write — placed after IDENTITY.md, SOUL.md, and KNOWLEDGE.md to prevent cascade failure if one gate stalls.
+11. Check context budget — auto-summarise if over threshold
+12. **Project the agent into the graph** — delegate to the `specialists:database-operator` specialist with the instruction: "Project public agent `{slug}` into the graph by POSTing to `/api/admin/agents/{slug}/project`." The route reads the on-disk files and idempotently MERGEs the `:Agent` node, the four owned `:KnowledgeDocument` projections (IDENTITY/SOUL/KNOWLEDGE/KNOWLEDGE-SUMMARY when present, namespaced `attachmentId="agent:<slug>:<role>"`), the `HAS_*` edges, and the `USES_KNOWLEDGE` edges to every operator-tagged doc. Loud-fail: if the route returns non-2xx, surface the error to the user verbatim — the agent's files exist on disk but its graph projection is incomplete, which means the operator's /graph view will not show this agent. Re-running the projection is safe; it is the same idempotent MERGE.
+13. Confirm creation: "Agent created. Visitors can reach it at `/{slug}`"
+
+### List
+
+Read `defaultAgent` from `account-manage` to identify the current default. Read all directories under `agents/`. For each, read `config.json` and estimate total token budget. Present as a structured summary, marking the default agent:
+
+**sales** — Sonnet Standard * default
+1 plugin · 11,500 / 200,000 tokens (6%) · active
+
+**support** — Haiku Low cost
+0 plugins · 3,200 / 40,000 tokens (8%) · active
+
+**public** — Haiku Low cost
+1 plugin · 9,800 / 40,000 tokens (25%) · active
+
+### Clone
+
+Copy the source agent's directory to a new slug. The user modifies what's different — typically SOUL.md and KNOWLEDGE.md.
+
+### Edit
+
+Read any file in the agent's directory and present it via document-editor with `filePath` set to the file's path. Write back on approval. The document-editor includes a Download button — the user can review, edit, then download the file as `.md` without further agent action.
+
+For agent image changes:
+- Use the `agent-image` tool with `action: "set"` to upload or replace the image
+- Use the `agent-image` tool with `action: "remove"` to remove the image (falls back to brand logo)
+- To change the shape, use `agent-image` with `action: "set"` and the new `imageShape`
+- To change `showAgentName` (`true`, `false`, or `"none"`), update `config.json` directly
+
+For knowledge scope changes:
+- Show currently tagged nodes (search `memory-search` without `agentSlug`, identify results whose `agents` property contains the agent's slug) and active keyword subscriptions (from `config.json`).
+- Allow adding/removing direct tags (add/remove the slug from nodes' `agents` arrays via `memory-write`).
+- Allow adding/removing keyword subscriptions (update `knowledgeKeywords` in `config.json`).
+- Allow toggling `liveMemory` on/off (update `config.json`).
+- After changes, offer to refresh KNOWLEDGE.md using the `update-knowledge` skill.
+
+**After every Edit operation that touches IDENTITY/SOUL/KNOWLEDGE/KNOWLEDGE-SUMMARY/`config.json` (including `liveMemory`, `knowledgeKeywords`, or direct-tag mutations), delegate to `specialists:database-operator` to re-project: POST `/api/admin/agents/{slug}/project`.** Without re-projection the on-disk files diverge from the graph state — the operator sees stale `:Agent` properties and stale `USES_KNOWLEDGE` edges in /graph. Loud-fail: surface non-2xx errors verbatim.
+
+### Delete
+
+Deletion removes the entire agent directory (`agents/{slug}/`) — not individual files. A partial deletion leaves ghost state that poisons future creation into the same slug.
+
+**Confirmation:** Before removing, show the user exactly what will be deleted — the slug, directory path, and the files present in it. Proceed only after explicit confirmation.
+
+**Default agent handling:** Read `defaultAgent` from `account.json` via `account-manage`. If the agent being deleted is the current default:
+- Scan `agents/` for other non-admin directories containing `config.json`. If other agents exist, offer to set one as the new default via `account-update`.
+- If no other agents remain (or the user declines to set a new default), clear the `defaultAgent` field by calling `account-update` with `field: "defaultAgent"`, `value: ""`. Tell the user that visitors to the root URL will see a "no agents" message until a new agent is created.
+
+**Cleanup sequence:**
+- Issue `DELETE /api/admin/agents/{slug}` — the route removes the `:Agent` node and its four owned `:KnowledgeDocument` projections FIRST, then deletes the directory. Loud-fail: if graph cleanup throws, files are preserved and a 500 is returned with the error text. Re-issuing the DELETE is safe (idempotent on both layers). Operator-tagged docs survive the projection delete — only the `USES_KNOWLEDGE` edges from this Agent are removed.
+- Verify the directory no longer exists
+- Report what was removed (list the files that were in the directory)
+
+**Graph tag cleanup (optional):** Knowledge nodes in the graph may have the deleted agent's slug in their `agents` array. These tags become orphaned after deletion — no agent will query them, so they are inert. Offer the user the choice: clean up the orphaned tags (remove the slug from each node's `agents` array via `memory-update`, reading the current array first to preserve other agents' tags) or leave them. If the user declines, note that the tags are harmless and can be cleaned up later.
+
+### Set as Default
+
+Change which agent serves the root URL (`public.maxy.bot/`).
+
+1. Read the current `defaultAgent` from `account-manage`
+2. Confirm the change with the user — show the current default and the proposed new default
+3. Call `account-update` with `field: "defaultAgent"`, `value: "{slug}"`
+4. Report the result — the tool response includes both old and new default slug
+
+The new default takes effect on the next page load. The previous default agent remains accessible at its `/{slug}` URL.
+
+### Test Greet
+
+Invoke the agent with `[New session. Greet the visitor.]` and stream the response to the admin chat. The admin sees exactly what a visitor would see on first load.
+
+## Self-Contained Constraint
+
+Public agents run via the direct Anthropic API. They have no filesystem access, no MCP tools, no subagents. The only tool is `render-component` (single-select and multi-select). Everything the agent needs must be in its directory files. The platform assembles these into the system prompt at invocation time.
+
+## URL Routing
+
+On the `public.*` subdomain:
+- `public.maxy.bot/` → the agent set as `defaultAgent` in account.json
+- `public.maxy.bot/{slug}` → named agent

package/payload/platform/plugins/admin/skills/publish-site/SKILL.md

@@ -0,0 +1,72 @@
+# Publish Site
+
+Move an already-extracted static-site tree into the per-account static-publish surface (`<accountDir>/sites/<slug>/`) and emit exactly one canonical path slug. Pair the slug with the deterministic public hostname returned by `mcp__admin__public-hostname` to surface the full URL in a single turn.
+
+**Invoked from `specialists:content-producer`** when the brief carries a host-website / publish-site / put-online intent (Task 966). Admin's IDENTITY.md routes those intents to that specialist on turn 1; running this skill inline on the main admin runner exhausts the 10-turn budget on per-turn ToolSearch + plugin-read discovery before publish-site executes.
+
+## When to Use
+
+Activate when **both** are true:
+
+- The current turn carries a "host this website" / "publish this site" / "put this online" / equivalent intent.
+- A directory tree of HTML + assets is already on disk under `<accountDir>/extracted/<attachmentId>/` (the typical output of [unzip-attachment](../unzip-attachment/SKILL.md)), or the conversation already names a source directory under `<accountDir>/`.
+
+Do **not** activate for `.pdf`, `.docx`, slide decks, single-image attachments, or zips whose extracted output is not a directory tree of HTML + assets — those have their own skills (`a4-print-documents`, `deck-pages`, etc.). The intent + tree shape is the gate.
+
+## Inputs
+
+- `source` — absolute path to the extracted directory tree (already produced by `unzip-attachment`).
+- `slug` — operator-supplied or operator-confirmed path under `<accountDir>/sites/`. One or more `/`-separated segments; each segment matches the platform's `SAFE_SEG_RE` (`/^[a-z0-9_][a-z0-9_.-]{0,99}$/i`); no segment starts with `.`; no segment equals `..`. Confirm with the operator before proceeding when the slug is not already explicit.
+
+## Invariants
+
+These are non-negotiable. Each is mechanically check-able and each maps to a fixed refusal log line.
+
+1. **Move, never copy.** The source tree is `mv`'d into `<accountDir>/sites/<slug>/`. No re-extraction, no `cp`. After success the source path no longer exists.
+2. **No filename invention.** Never `cp <any>.html index.html` to satisfy a URL form. If the moved tree's top level has no `index.html`, the canonical path slug points at the actual landing HTML by name.
+3. **One emitted path slug.** The skill emits exactly one path string starting with `/sites/`:
+   - `/sites/<slug>/` — when `<accountDir>/sites/<slug>/index.html` exists after the move.
+   - `/sites/<slug>/<file>.html` — when no `index.html` and exactly one HTML file sits at the top level.
+4. **Path only — no scheme, no host.** The emitted string is a path. Never emit a URL with a scheme or a host. The operator pairs the slug with their own public-host root.
+5. **No fallback servers, no Playwright probes, no service restarts.** If the move or URL form is wrong, refuse. Reaching for `python -m http.server`, `npx http-server`, browser-automation probes, or platform restarts in place of fixing the URL contract is the prior-session failure pattern this skill exists to close.
+6. **Source must be a real directory tree, no symlinks.** If `find <source> -type l` returns any entry, refuse.
+
+## Refusals
+
+Each refusal is a `[publish-site] refused` log line plus a fixed operator message. No retry, no silent substitution.
+
+| Reason | Trigger | Log line |
+|---|---|---|
+| `unsafe-slug` | Any segment fails `SAFE_SEG_RE`, has a leading `.`, or equals `..` | `[publish-site] refused reason=unsafe-slug slug=<value>` |
+| `destination-occupied` | `<accountDir>/sites/<slug>/` already exists with non-empty contents | `[publish-site] refused reason=destination-occupied dest=<path>` |
+| `symlink-in-source` | `find <source> -type l` returns at least one entry | `[publish-site] refused reason=symlink-in-source entry=<path>` |
+| `zero-html` | The top level of `<source>` has no `*.html` files | `[publish-site] refused reason=zero-html source=<path>` |
+| `ambiguous-html` | Multiple top-level `*.html` files and no `index.html` | `[publish-site] refused reason=ambiguous-html candidates=<f1>,<f2>,...` |
+
+The operator message for `ambiguous-html` names the candidate files and asks the operator to pick which file is the landing page (or to add an `index.html` to the source). No move happens until the choice is explicit.
+
+## Flow
+
+1. **Resolve and validate slug.** Split on `/`; reject any segment that violates the rules above.
+2. **Pre-flight checks.** Inspect the source tree's top level: count `*.html` files; check for `index.html`; run the symlink scan; check the destination is absent or empty. Apply refusals before any disk mutation.
+3. **Move.** Single `mv <source> <accountDir>/sites/<slug>/`. Emit one log line:
+   `[publish-site] move from=<source> to=<accountDir>/sites/<slug>/ files=<n>`
+4. **Choose the canonical path.** `index.html` present at top level → path is `/sites/<slug>/`. Otherwise the single top-level HTML file → path is `/sites/<slug>/<file>.html`.
+5. **Emit.** One log line:
+   `[publish-site] url emitted=<path-slug> kind=<index|file>`
+6. **Resolve the public hostname and emit the full URL.** Call `mcp__admin__public-hostname` to fetch this account's hostname; the tool reads `cloudflared/config.yml` + `alias-domains.json` — the same files the platform server trusts to route. Concatenate `https://<hostname><path-slug>` and surface that one URL to the operator. If the tool returns `reason: no-tunnel`, relay the tool's remediation message verbatim — do not improvise the URL. The route at `/sites/*` (see [server/routes/sites.ts](../../../../ui/server/routes/sites.ts)) handles the trailing-slash redirect on the dir form, so the slug is correct as-emitted whether the operator's HTML uses an `index.html` entry-point or a publisher-named landing file.
+
+## Log lines (grep targets)
+
+| When | Line |
+|---|---|
+| After move | `[publish-site] move from=<src> to=<dest> files=<n>` |
+| Path emission | `[publish-site] url emitted=<path-slug> kind=<index\|file>` |
+| Refusal (any reason) | `[publish-site] refused reason=<unsafe-slug\|destination-occupied\|symlink-in-source\|zero-html\|ambiguous-html> <key=value pairs>` |
+
+## Out of scope
+
+- Cleanup of pre-existing synthetic files left by earlier sessions (e.g. a stray `index.html` produced by an earlier `cp brochure.html index.html` workaround). Refuse with `destination-occupied` and let the operator clean up explicitly.
+- Extraction. `unzip-attachment` already owns the extract step; the source path is its output.
+- DNS, tunnels, certificates, or any public-host configuration. The route at `/sites/*` is the wire contract; this skill is a placement + URL-shape skill only.
+- Per-directory default-filename config (e.g. a `.publish.json` that names a default landing file). The publisher names the landing file; no inference layer.

package/payload/platform/plugins/admin/skills/qr-code/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: qr-code
+description: >
+  Generate QR codes from URLs, Wi-Fi credentials, contacts (vCard), email/SMS links,
+  or plain text and deliver the image inline. Trigger phrases: "QR code", "generate a
+  QR", "create a QR", "make a QR code for", or any request to share data as a scannable code.
+---
+
+# QR Code Generation
+
+Generate QR codes from user-provided data and deliver the resulting image inline in conversation.
+
+## When to Activate
+
+- User asks to generate, create, or make a QR code
+- User wants to share a URL, Wi-Fi password, or contact details as a scannable code
+- Any mention of "QR" in the context of creating one
+
+## Behaviour
+
+Infer the data type from the user's input. For structured types (Wi-Fi, vCard), collect any missing fields conversationally and confirm the structured data before encoding. For simple types (URL, plain text, email, SMS), encode directly.
+
+Generate the QR image by piping the encoded string to the `qrcode` CLI via stdin — never interpolate user data into the shell command. Save the output as PNG to `/tmp/` and present the file to the user.
+
+If the CLI exits with an error, report the error message to the user and suggest corrections (e.g., data too long, invalid format).
+
+## Boundaries
+
+- Generates one QR code per request. Bulk generation is not supported.
+- No branded/styled QR codes (logo overlays, custom colours).
+- Does not scan or read existing QR codes.
+
+## References
+
+Load `references/data-formats.md` for encoding formats, CLI invocation patterns, and supported options.

package/payload/platform/plugins/admin/skills/qr-code/references/data-formats.md

@@ -0,0 +1,113 @@
+# QR Code Data Formats & CLI Reference
+
+## CLI Invocation
+
+Always pipe data via stdin to avoid shell injection. Never interpolate user data into the command string.
+
+```bash
+printf '%s' 'ENCODED_DATA' | npx -y qrcode -o /tmp/qr-$(date +%s).png
+```
+
+### Options
+
+| Option | Flag | Values |
+|--------|------|--------|
+| Size | `--width` | Small: 200, Medium: 400 (default), Large: 800 |
+| Error correction | `--error-correction-level` | L (7%), M (15%, default), Q (25%), H (30%) |
+| SVG output | `--type svg -o /tmp/qr-$(date +%s).svg` | Use instead of PNG when user requests SVG |
+
+Higher error correction allows the QR code to remain scannable even if partially damaged, but reduces data capacity.
+
+## Data Capacity
+
+QR codes have a maximum capacity that depends on the error correction level:
+
+| EC Level | Alphanumeric max | Binary max |
+|----------|-----------------|------------|
+| L | 4,296 | 2,953 |
+| M | 3,391 | 2,331 |
+| Q | 2,420 | 1,663 |
+| H | 1,852 | 1,273 |
+
+If the encoded data exceeds capacity, the CLI will error. Tell the user the data is too long and suggest reducing it or lowering the error correction level.
+
+## Encoding Formats
+
+### URL
+
+Encode the URL as-is. No special formatting needed.
+
+```
+https://example.com/path?query=value
+```
+
+### Plain Text
+
+Encode the text as-is.
+
+### Wi-Fi
+
+Collect from the user: network name (SSID), password, and encryption type.
+
+| Field | Required | Values |
+|-------|----------|--------|
+| SSID | Yes | The network name |
+| Password | Yes (unless open) | The network password |
+| Encryption | Yes | WPA (covers WPA2/WPA3), WEP, or nopass |
+| Hidden | No | true if the network is hidden (default: false) |
+
+Default encryption to WPA if the user doesn't specify.
+
+```
+WIFI:T:WPA;S:MyNetwork;P:MyPassword;;
+WIFI:T:WPA;S:MyNetwork;P:MyPassword;H:true;;
+WIFI:T:nopass;S:OpenNetwork;;;
+```
+
+Special characters in SSID or password (`;`, `,`, `"`, `:`, `\`) must be escaped with a backslash.
+
+### vCard (Contact)
+
+Collect from the user: at minimum a name. Phone and email are optional but encouraged.
+
+```
+BEGIN:VCARD
+VERSION:3.0
+N:LastName;FirstName;;;
+FN:FirstName LastName
+TEL;TYPE=CELL:+441234567890
+EMAIL:person@example.com
+ORG:Company Name
+TITLE:Job Title
+URL:https://example.com
+END:VCARD
+```
+
+Omit any field the user doesn't provide. Do not add placeholder values.
+
+### Email (mailto)
+
+```
+mailto:recipient@example.com
+mailto:recipient@example.com?subject=Hello&body=Message%20here
+```
+
+URL-encode the subject and body values.
+
+### SMS
+
+```
+sms:+441234567890
+sms:+441234567890?body=Message%20here
+```
+
+URL-encode the body value.
+
+## Error Handling
+
+| Error | Cause | User-facing message |
+|-------|-------|-------------------|
+| CLI exits non-zero | Various | Report the stderr output and suggest the user check their input |
+| "Input too long" | Data exceeds QR capacity | "The data is too long for a QR code. Try shorter text or a lower error correction level (L instead of M)." |
+| npm/npx failure | Package not available | "QR code package couldn't be downloaded. Check your internet connection and try again." |
+| File write error | Permission or disk issue | "Couldn't save the QR code image. Check disk space and try again." |

package/payload/platform/plugins/admin/skills/skill-builder/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: skill-builder
+description: "Guide the user through creating a new lean skill — collect name, description, behaviour rules, and references, then save the skill to memory."
+---
+
+# Skill Builder
+
+A deterministic walkthrough for creating new lean skills. Follow each step in order. Be conversational — one question at a time.
+
+## When to Activate
+
+The admin requests a new skill, asks to "create a skill", "add a skill", or "teach you something new".
+
+## Before Starting
+
+Load `references/lean-pattern.md` for the template and examples. Use it throughout as your reference for correct structure.
+
+## Step 1: Understand the Purpose
+
+Ask: **"What should this skill do?"**
+
+Listen for:
+- What capability it adds (scheduling, quoting, inventory, etc.)
+- When it should activate (what triggers it)
+- What tools or data it needs (memory, web search, file access, etc.)
+
+Clarify until you can describe the skill in one sentence. This becomes the `description` in frontmatter.
+
+## Step 2: Choose a Name
+
+Propose a name based on the purpose. Names must be:
+- Lowercase
+- Hyphen-separated (e.g. `inventory-management`)
+- Short and descriptive
+
+Confirm with the user.
+
+## Step 3: Define Behaviour
+
+Ask what rules the agent should follow when using this skill:
+- **Tone and style** — formal, casual, WhatsApp-short?
+- **Activation conditions** — when exactly should the agent use this skill?
+- **Hard boundaries** — what should the agent never do?
+- **Data sources** — where does the skill's knowledge live? (memory, external API, files)
+- **Escalation** — when should it hand off to admin?
+
+Not every skill needs all of these. Only include what's relevant.
+
+If the skill involves generating PDFs or print-ready documents, load `references/pdf-generation.md` for the constraints on HTML layout and the `browser_pdf_save` rendering path.
+
+## Step 4: Decide on References
+
+If the skill has detailed procedures, templates, or data formats, those belong in `references/` files — not inline in SKILL.md.
+
+Ask: **"Are there any detailed procedures, templates, or formats this skill needs?"**
+
+For each reference file:
+- Give it a descriptive filename (e.g. `event-format.md`, `quoting-rules.md`)
+- Collect the content from the user — they can dictate, paste, or describe it and you draft it
+
+If the skill is simple enough to fit in SKILL.md alone (under ~30 lines of instructions), skip references.
+
+## Step 5: Choose an Icon
+
+Ask: **"Would you like to pick an icon for this skill?"**
+
+Icons give skills a visual identity. They use [Lucide](https://lucide.dev) icon names. Offer a few suggestions that match the skill's purpose — the reference file `references/lean-pattern.md` has a curated list.
+
+If the user picks one, note it as part of the skill record. If they skip this, omit it — it's optional.
+
+## Step 6: Compose the Skill
+
+Using the lean pattern from `references/lean-pattern.md`, compose:
+
+1. **SKILL.md** — frontmatter (`name`, `description`) + activation conditions + behaviour rules + references index
+2. **Reference files** — one per detailed topic
+
+Show the user the complete SKILL.md content and each reference file. Ask them to review.
+
+## Step 7: Save the Skill as a Plugin File
+
+Use `store-skill` to write the composed skill to disk as part of an admin-managed plugin. The tool computes the path internally — supply the names and content only.
+
+Pick a `pluginName` that groups related operator-authored skills (e.g. `beacons-skills`, `my-utils`). Reuse the same `pluginName` across calls so the skill joins existing operator skills under one plugin. If this is the first skill in a new plugin, the tool creates the `PLUGIN.md` automatically.
+
+```
+store-skill({
+  pluginName: "{kebab-case plugin name}",
+  skillName: "{kebab-case skill name}",
+  description: "{the one-sentence description from Step 1}",
+  publicEmbed: false,
+  body: "{SKILL.md body content WITHOUT frontmatter — activation conditions, behaviour rules, references index}",
+  references: [
+    { filename: "{kebab-case-name}.md", content: "{full reference body}" }
+  ]
+})
+```
+
+Set `publicEmbed: true` only when the user wants this skill surfaced to the public agent. Default to `false` for admin-only skills.
+
+`references` is optional — pass `[]` (or omit) when the skill has no detailed procedures or templates.
+
+## Step 8: Confirm
+
+Tell the user:
+
+> "Your skill is saved on disk as part of the `{pluginName}` plugin and is active right now for the admin agent. I can use it when the situation matches. To edit it later, ask me to update the skill — I'll re-run `store-skill` with the new content."
+
+If `publicEmbed: true`, add: "It will surface in the public agent on the next session start."
+
+---
+
+**Remember:** Be conversational. Don't dump all questions at once. Guide through each step one at a time.