@rubytech/create-maxy-code 0.1.0

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

@@ -0,0 +1,255 @@
+# Onboarding
+
+Guided first-run setup for new installations. The web UI offers a skip/guided choice before Claude OAuth — if the user skips, defaults are applied server-side for steps 1-6 and the agent resumes from step 7. This runs automatically at every session start when `currentStep` is less than 9. 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.
+
+**Turn-completion contract.** Any onboarding turn that advances `currentStep` (via `onboarding-complete-step`) OR narrates a step transition with phrases like "Moving to step N", "Proceeding to step N", "Step N done" MUST end with one of: a `render-component` call surfacing the next step's UI, OR a `?`-terminated question. Bare prose statements like "Moving to step 9 — operator persona and profile bootstrap." with nothing after are forbidden — they leave the operator with no actionable surface and force a manual nudge. Same rule applies turn-by-turn through step 9. The post-restart resume contract for step 7 is the canonical case: when the operator's "Cloudflare setup completed" message arrives post-restart at `currentStep=7`, the agent's first turn must acknowledge AND immediately render the step-8 prompt (or `anthropic-setup`'s next surface) without an intervening dead-end paragraph.
+
+## Step 1 — Plugin selection
+
+*(skip if `currentStep` >= 1)*
+
+Call `onboarding-plugin-options` — it returns the fully-assembled options array with correct classification (core → locked, defaultEnabled → recommended, available → optional) derived from brand.json. Do not reclassify, reorder, or transform the entries — use them as-is.
+
+Append one additional entry to the end of the array: `{ value: "stripe", label: "stripe", description: "Live access to payment and business data.", group: "Claude Official" }`.
+
+Then append three entries from the Anthropic verticals marketplaces (`claude-for-financial-services` and `knowledge-work-plugins`). Default: not selected — the user picks each deliberately:
+
+- `{ value: "kyc-screener", label: "kyc-screener", description: "Parses onboarding documents, runs the rules engine, flags gaps. Outputs are draft work product for human review — your compliance specialist owns sign-off. UK estate agents under MLR 2017 are AML-regulated; this is the natural fit. Install: claude plugin install kyc-screener@claude-for-financial-services", group: "Claude Anthropic verticals" }`
+- `{ value: "meeting-prep-agent", label: "meeting-prep-agent", description: "Briefing pack before every client meeting, FSI-flavoured templates. Overlaps with the business-assistant calendar-prep flow; pick one path deliberately rather than running both. Install: claude plugin install meeting-prep-agent@claude-for-financial-services", group: "Claude Anthropic verticals" }`
+- `{ value: "pdf-viewer", label: "pdf-viewer", description: "Live interactive viewer to view, annotate, and sign PDFs — mark up contracts, fill forms, stamp approvals, place signatures, then download the annotated copy. Click-through replaces conversation for this surface (v0.2.0, different integration shape from the chat-driven skills). Install: claude plugin install pdf-viewer@knowledge-work-plugins", group: "Claude Anthropic verticals" }`
+
+Call `render-component` with `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` set to the array from the tool (with the Claude Official and Claude Anthropic verticals entries appended).
+
+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 **Claude Anthropic vertical**, run the install command quoted verbatim in that entry's description:
+  - `kyc-screener` → `claude plugin install kyc-screener@claude-for-financial-services`
+  - `meeting-prep-agent` → `claude plugin install meeting-prep-agent@claude-for-financial-services`
+  - `pdf-viewer` → `claude plugin install pdf-viewer@knowledge-work-plugins`
+- For each selected **{{productName}} 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. When step 1 is the step being completed, also pass `acceptedAnthropicVerticals` and `declinedAnthropicVerticals` derived from the user's submission against the closed Anthropic-verticals set `{kyc-screener, meeting-prep-agent, pdf-viewer}` — `acceptedAnthropicVerticals` is the intersection of the submission with that set, and `declinedAnthropicVerticals` is the set minus the intersection. Both arrays must be passed together: this emits `[plugin-onboarding] group=anthropic-verticals accepted=<n> declined=<n>`, the paired counter to Task 976's `presented=3` line.
+
+If any {{productName}} plugins were enabled in this step, call `session-reset` immediately after completing step 1. {{productName}} 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 {{productName}} plugins were enabled (user skipped or selected only Claude Official plugins), proceed directly to Step 2 — no reset needed.
+
+## Step 2 — WiFi setup
+
+*(skip if `currentStep` >= 2)*
+
+Connect the device to WiFi so it can operate without an ethernet cable. This step is skippable — ethernet users who prefer a wired connection can skip and set up WiFi later through conversation at any time.
+
+First, check whether the device has WiFi hardware by calling the `wifi` tool with `action: "status"`. If the result says "No WiFi hardware detected", skip this step automatically — tell the user their device does not have WiFi capability and proceed to the next step. Call `onboarding-complete-step` with step 2.
+
+If WiFi hardware is present, check whether the device is already connected to a WiFi network. If the `wifi status` result shows an active WiFi connection with an IP address, confirm with the user: "You're already connected to WiFi network **{ssid}**. Would you like to keep this connection or switch to a different network?" If they want to keep it, call `onboarding-complete-step` with step 2 and proceed.
+
+If WiFi hardware is present but not connected, ask: "Would you like to connect to WiFi? This lets your device work without an ethernet cable. You can skip this and set up WiFi later if you prefer."
+
+If the user wants to proceed:
+
+1. Call the `wifi` tool with `action: "scan"` to list visible networks.
+2. Call `render-component` with `name: "single-select"` and data with `submitMessage: "Connect to {{value}}"` and `options` built from the scan results — each network as `{ value: "<ssid>", label: "<ssid>", description: "<signal>% signal — <security>" }`. Sort by signal strength descending. If your network doesn't appear in the list, you can connect by name — just tell me the SSID and password.
+3. Wait for the user's selection. Then ask for the WiFi password via conversation (do not use a rendered component for passwords).
+4. Call the `wifi` tool with `action: "connect"`, the selected `ssid`, and the `password`.
+5. If the connection succeeds and an IP is assigned, the tool confirms it is safe to unplug ethernet. If the connection fails (wrong password, network not found, no IP assigned), show the error and offer to retry or skip.
+
+After the WiFi is connected (or the user skips), call `onboarding-complete-step` with step 2.
+
+## Step 3 — Output style
+
+*(skip if `currentStep` >= 3)*
+
+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 3.
+
+## Step 4 — Thinking view
+
+*(skip if `currentStep` >= 4)*
+
+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 4.
+
+## Step 5 — Timezone
+
+*(skip if `currentStep` >= 5)*
+
+The platform auto-detected the server's timezone and stored it on the user's profile at first login. Confirm it with the user so scheduling, cron events, and time formatting use the correct locale.
+
+Call `profile-read` to retrieve the current `UserProfile`. Extract the `timezone` field. If it is already set, present it for confirmation: "Your timezone is set to **{timezone}**. Is this correct?"
+
+Call `render-component` with `name: "single-select"` and data with `submitMessage: "Set timezone to {{value}}"` and `options` as an array. Include the auto-detected timezone as the first (default) option, plus common alternatives:
+
+- `{ value: "{current_timezone}", label: "{current_timezone}", description: "Auto-detected from your device." }`
+- `{ value: "Europe/London", label: "Europe/London", description: "GMT / BST" }`
+- `{ value: "America/New_York", label: "America/New_York", description: "Eastern Time" }`
+- `{ value: "America/Los_Angeles", label: "America/Los_Angeles", description: "Pacific Time" }`
+
+Omit any option that duplicates the auto-detected timezone. If the user selects "Other", ask them to type their IANA timezone identifier (e.g. `Asia/Tokyo`, `Australia/Sydney`).
+
+After the user confirms or selects a timezone, call `profile-update` with `profileFields: { timezone: "<selected_value>" }`. Call `onboarding-complete-step` with step 5.
+
+## Step 6 — Admin personality
+
+*(skip if `currentStep` >= 6)*
+
+Write the admin agent personality. All paths are relative to the account directory (the working directory).
+
+First, check whether personalisation is already complete: read `agents/admin/SOUL.md`. If it contains actual business content (not just the `# Soul` header), call `onboarding-complete-step` with step 6 and skip to business onboarding — the personalisation is already in place.
+
+If the admin SOUL file (`agents/admin/SOUL.md`) is empty or missing content, the user must provide personalisation input through conversation. Ask the user about:
+
+- Tone and personality: how the agent should sound (formal, casual, warm, blunt, etc.), language preferences
+- Working style: how the agent should collaborate — proactive vs. wait-for-instruction, terse vs. explanatory, how to handle uncertainty
+
+Do NOT ask about the business itself here — customer description, current stage, industry, services, etc. belong in the graph via the `business-profile` skill (step 9), not in SOUL. SOUL is the agent's personality template; asking business-identity questions in step 6 pushes factual data into the wrong layer.
+
+SOUL contains tone, language, working style, and the agent's role within the business — factual business data lives in the graph, not here.
+
+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.
+
+After the admin SOUL is written and approved, call `onboarding-complete-step` with step 6.
+
+**Document ingestion.** If the user uploaded any documents during Step 6 (or earlier in the session), dispatch the `specialists:database-operator` subagent (via the universal `document-ingest` skill) to ingest them AFTER calling `onboarding-complete-step` — not before. Use the Agent tool with `run_in_background: true`. The critical path (SOUL file, step completion) must not depend on document ingestion succeeding. Include the document path, the document subject (typically the account owner's UserProfile or the LocalBusiness depending on the doc), and the scope in the brief. If no documents were uploaded, skip this step.
+
+**Next steps.** After completing onboarding, let the user know that everything configured during onboarding — plugins, WiFi, output style, thinking view, timezone, and personality — can be changed at any time through conversation. Then suggest three things the user can do next — all optional and available whenever they are ready:
+
+1. **Set up remote access** — Cloudflare Tunnel connects the platform to a custom domain so the user and their customers can reach it from anywhere. Ask to get started.
+2. **Set up the public-facing agent** — an Anthropic API key lets visitors chat with the business. Ask to get started.
+3. **Capture the business profile** — identity, address, hours, services, FAQs. This populates the graph so the agent can answer business questions and so public-facing customers get accurate information. Ask to get started.
+
+## Step 7 — Cloudflare Tunnel
+
+*(skip if `currentStep` >= 7)*
+
+Remote access via a custom domain. Without this, the platform is only reachable on the local network.
+
+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 skips, let them know they can set up Cloudflare at any time by asking. Also mention that remote access is still possible without Cloudflare — WhatsApp, Telegram, and Email channels all connect directly to the device, so the user (and their customers) can reach the agent from anywhere through those channels without needing a tunnel or custom domain. Call `onboarding-complete-step` with step 7.
+
+If the user wants to proceed, first confirm the domain state in one sentence: "Is your domain already on a Cloudflare account?" If not, quote the click-path from `plugins/cloudflare/references/dashboard-guide.md` § "Add a domain to a Cloudflare account" and wait for the user to confirm the zone is **Active**.
+
+Then call `render-component` with `name: "cloudflare-setup-form"` and data containing only the form copy — the form self-discovers the admin/public/apex domain options from the operator's logged-in Cloudflare dashboard via `/api/admin/cloudflare/domains`. Do not read `brand.json` for domain options; brand identity has no authority over what zones the operator's Cloudflare account holds. The form collects admin label + admin domain + optional public label + public domain + optional apex + admin password in one submission, then the submit handler runs `setRemotePassword`, `~/setup-tunnel.sh`, and alias-domain writes server-side and relays the script's output — including any `ACTION REQUIRED` block — back as the component's submitted payload.
+
+```
+{
+  title: "Set up remote access",
+  description: "Connect your device to a custom domain.",
+  submitLabel: "Set up Cloudflare"
+}
+```
+
+Wait for the user's submission. The `_componentDone` payload contains the `setup-tunnel.sh` output verbatim. Relay that output to the user — quote any `ACTION REQUIRED` block exactly. When the script exits zero, step-7 completion has already been persisted by the script itself — relay the output and stop. Do not call `onboarding-complete-step` with step 7; the script is the authority for step-7 completion, and any call you make after the script's restart dispatch would race the service restart and almost always lose. If the script failed (the endpoint returned `ok: false, field: "script"`), the form surfaced the error and stayed open — relay the output, cite `plugins/cloudflare/references/reset-guide.md` for recovery, and offer to re-render the form after any manual steps. Do not synthesise alternative recovery commands. If the user skipped (step 7 not reached), call `onboarding-complete-step` with step 7 so the next session resumes at step 8.
+
+**Post-restart resume contract.** A successful Cloudflare setup arms a brand-service restart that kills the in-flight admin agent. The operator's "Cloudflare setup completed" message is replayed by the chat client after the restart cycle completes. Two pathways converge on the same agent-visible outcome:
+- **Default (Task 982).** The operator's admin sessionKey is a Task-653-style signed token (`v1.…` HMAC) that survives the restart. `validateSession` rehydrates the in-memory session from the token, the chat-route binds the prior `conversationId` via `getMostRecentAdminConversationForUser`, and the SDK's next cold-create passes `resume: <priorAgentSessionId>` — the marker turn lands in the SAME conversation with the SDK's JSONL transcript intact.
+- **Fallback.** If the signed-token rehydrate fails (token tampered, TTL expired, pre-Task-982 legacy sessionKey), the chat client falls through to `POST /api/admin/sessions/<cid>/resume` via the surviving `__remote_session` cookie. Outcome from your view as the admin agent is identical.
+
+By the time you receive the marker, `OnboardingState.currentStep` is already 7 (the script's filesystem flag was consumed by `consumeStep7FlagUI` on the way in). The operator told you "Cloudflare setup completed (actionId: …)" at currentStep=7. Acknowledge, then proceed to step 8 — do NOT re-ask the Cloudflare question, do NOT re-render the cloudflare-setup-form, do NOT call `onboarding-complete-step` with step 7 (already done). The marker turn is your single source of truth that step 7 finished cleanly; the script's flag-consume is the orthogonal proof that the state machine advanced.
+
+## Step 8 — Anthropic API key
+
+*(skip if `currentStep` >= 8)*
+
+The public-facing agent uses the Anthropic API directly. Without a key, visitors cannot chat with the business. This step is optional — the user can skip it and set up the API key at any time through conversation.
+
+Call `anthropic-setup` with no arguments. If it returns `complete`, the key is already stored and working — call `onboarding-complete-step` with step 8 and skip ahead.
+
+If it returns `not_needed`, the tool detected that no public-facing endpoint is configured (the operator skipped step 7 or completed it without a public hostname). Relay the tool's `message` verbatim to the user, then call `onboarding-complete-step` with step 8 and skip ahead. Do not prompt them to set up the key — there is nothing for it to power yet.
+
+If it returns `awaiting_signin` (no stored key), ask: "Would you like to set up the API key for your public-facing agent now? This is what lets visitors chat with your business. You can skip this and set it up later if you prefer."
+
+If the user skips, let them know: "No problem — you can ask me to set up the API key whenever you're ready. Your admin agent works without it; only the public-facing agent needs it to handle visitor conversations." Call `onboarding-complete-step` with step 8.
+
+If the user wants to proceed, the tool returned a `url` and an `action` in `data`. Call `render-component` with `name: "browser-viewer"` and `data: { title: "Anthropic Console" }`, then use `browser_navigate` to open the URL. Explain: this uses the Anthropic Console (platform.claude.com), which is a separate service from the Claude account signed into earlier. Anthropic keeps the two — Claude and the API Console — as independent services with separate sessions and billing, even though the same credentials work on both.
+
+Immediately after navigating, run the `action` from the tool's response: call `browser_evaluate` with the `function` from `data.action.params`. Do not wait for the user to confirm sign-in — the evaluate checks the browser session state directly. Take the string result and pass it back by calling `anthropic-setup` again with `consoleResult` set to that string. Handle the returned `status`:
+
+- `awaiting_signin`: The browser has no active Console session. The response includes a new `action` for re-evaluation. Tell the user they need to sign in at the Console. When they confirm they have signed in, run the `action` from the response (call `browser_evaluate` with `data.action.params.function`), pass the result back to `anthropic-setup` with `consoleResult`, and handle the status again.
+- `awaiting_credits`: The user is signed in but has no credits. The response includes a new `action` for re-evaluation. Relay the message (it contains the billing URL). When the user confirms they have added credits, run the `action` from the response, pass the result back to `anthropic-setup` with `consoleResult`, and handle the status again.
+- `complete`: Call `onboarding-complete-step` with step 8.
+- `error`: Relay the message. Offer to try again or skip.
+
+All retry loops re-evaluate using the `action` returned in the most recent response. Never re-call `anthropic-setup` with no arguments to get a fresh action — that restarts from Phase 1 and re-checks the stored key unnecessarily.
+
+Do not read any skill files. Do not call any other Anthropic tools except `anthropic-setup`. Do not dispatch specialists. The `anthropic-setup` tool handles the entire flow.
+
+## Step 9 — Operator persona and profile bootstrap
+
+*(skip if `currentStep` >= 9)*
+
+Pin the operator's persona and bootstrap the graph nodes the platform requires before any further writes. The persona choice is the trust-shaping moment for this step — answering "what's your business?" with an employer's name silently registers a `LocalBusiness` owned by the wrong party, so we must surface the question explicitly before any write. "Just for me" covers anyone using {{productName}} for personal use, including someone with an employer that is not being registered here.
+
+**Render the persona select first.** Call `render-component` with `name: "single-select"` and data:
+
+```
+{
+  submitMessage: "Persona: {{value}}",
+  options: [
+    {
+      value: "personal",
+      label: "Just for me",
+      description: "I am not setting this up for a business — {{productName}} is my personal operations agent."
+    },
+    {
+      value: "business-owner",
+      label: "For my business",
+      description: "I am the owner / operator and {{productName}} is the operations agent for my company."
+    }
+  ]
+}
+```
+
+**Wait for the user's submission.** If the user picks "Other" or types free text instead of selecting, ask them which of the two personas best describes them and re-render the select. Do not proceed without one of the two documented modes — the agent must not improvise a third path. If the user pivots off-topic mid-flow, answer their question briefly and re-render the select; step 9 stays incomplete until they pick a mode.
+
+**Call `onboarding-step9-mode` with the chosen mode before any graph write or skill invocation.** The tool emits the diagnostic log line and returns the deterministic next-action prose.
+
+**Open the action record with `task-create`.** Before any graph write or skill invocation, call `task-create` with:
+
+- `name`: "Establish operator owner — onboarding step 9"
+- `description`: a one-line summary describing the chosen mode and what entities will be produced
+- `status`: `"running"`
+- `kind`: `"onboarding-establish-owner"`
+- `inputsProvided`: the keys you actually pass on `inputs` (e.g. `["mode"]`); records the call shape
+- `inputs`: the form payload known at creation time — `{ mode: "personal" | "business-owner" }`
+- `inputSchema`: `{ secretFields: [] }` — the step-9 mode select carries no secrets; declare the empty list explicitly so the contract is visible at the call site
+
+The returned `taskId` is the audit handle for this step — every subsequent `memory-write` for `Person`, `UserProfile`, `AdminUser`, `Organization`, or `LocalBusiness` MUST pass it as `producedByTaskId` so the platform composes a `:PRODUCED` edge from the Task into the write. The Task is auto-linked to the current `AdminConversation` via `RAISED_DURING`, so `MATCH (c:AdminConversation)<-[:RAISED_DURING]-(t:Task)-[:PRODUCED]->(entity)` traverses from the conversation that initiated onboarding.
+
+**Recording what you collect.** The `onboarding-establish-owner` Task is the audit record for step 9. Record every operator-meaningful fact you collect using the existing surfaces — `description` for the running summary, `note` (via `task-update`) for facts as they land (email collected, phone declined, resolved Person/UserProfile elementIds), `appendStep` for phase markers. Agent's judgement decides which slot. Contract: by `task-complete`, a reader of the Task properties can reconstruct what was collected, what was declined, and which entities were touched without consulting any other source. No secrets in any property regardless of slot — `task-create`'s `inputs` is centrally redacted via `inputSchema.secretFields`; the post-creation slots carry no schema, so the agent's responsibility is to never write secret material into them.
+
+Then branch on the mode.
+
+### `business-owner`
+
+Invoke the `business-profile` skill, passing the `taskId` so the skill can thread it as `producedByTaskId` into every `memory-write` it issues. The skill follows its first-run path: create the `AdminUser` node, create the `LocalBusiness` node, create the `Organization` node, collect identity + address + whichever additional domains (hours, services, FAQs, brand assets) the user provides. When `business-profile` reports that the required nodes exist in the graph, call `task-update` with both `appendStep:"business-profile-complete"` AND `note:"Business profile complete — AdminUser=<elementId>, LocalBusiness=<elementId>, Organization=<elementId>"` (the resolved elementIds from the skill's writes; one call carries both the phase marker and the audit content). Then write the `HAS_PROFILE` edge from the personal-profile `Person` to the operator's `UserProfile` via `memory-update` (one `memory-search` to resolve both elementIds; the `UserProfile` already exists from step 6 onwards via the lazy-create in `loadUserProfile`). Then call `task-complete(taskId)` and `onboarding-complete-step` with step 9. Do not mark step 9 complete before the required nodes + the HAS_PROFILE edge exist — the precondition must be real, not just recorded.
+
+### `personal`
+
+Personal mode does not register a `LocalBusiness`. The `AdminUser` and personal-profile `Person` nodes were written deterministically at PIN setup time (the bootstrap path runs as `createdBy.agent === 'system'`), so this step only enriches the existing Person with operator-identity fields and links it to the `UserProfile`:
+
+1. **Elicit Person properties that help {{productName}} serve this operator.** Open by default — identity (email, phone, names), context (where they live, languages they speak, what they do, who they work for), or anything else the operator volunteers that makes future assistance more useful. The personal-profile Person is comprehensive, not enumerated: ask in one short conversational message for what feels natural to volunteer at first contact, accept whatever the operator offers, do not chase a fixed list. The user may decline any field; record what they provide.
+2. **Persist via `profile-update.personFields`.** Pass a single object whose keys are the Person properties the operator volunteered, in the operator's volunteered phrasing — the central schema validator handles synonyms (e.g. `phone` rejects with "use telephone") and Forbidden Properties (e.g. `name` rejects with "use givenName + familyName"); the agent does not pre-rewrite. The tool resolves the personal-profile Person via `(au:AdminUser {userId:$you})-[:OWNS]->(p:Person)` server-side and throws loudly if the OWNS edge is missing rather than silently no-oping (the PIN-setup path is the only place that edge is created — a missing edge means PIN setup never ran or was rolled back).
+3. **Append the step + record the facts.** Call `task-update` with both `appendStep:"identity-attached"` AND `note:"Identity attached — email=<value-or-declined>, telephone=<value-or-declined>"` (use the actual values the operator supplied; for declines write the literal `declined`). One call, both fields. The note carries the operator-meaningful audit content; the step is the phase marker.
+4. **Link the personal-profile `Person` to the `UserProfile`.** Call `memory-search` to resolve the `UserProfile` elementId for the operator (the lazy `loadUserProfile` write created it on the first admin session). Then call `memory-update` on the Person to add the `HAS_PROFILE` edge to the UserProfile. (`HAS_PROFILE` from `:Person` is a sibling pattern to the existing `AdminUser→HAS_PROFILE→UserProfile`; both are valid sources for the same edge type. See [schema-base.md Relationship Patterns](../../../memory/references/schema-base.md).)
+5. **Close the action record.** Call `task-update` with both `appendStep:"profile-linked"` AND `note:"Profile linked — Person=<elementId>, UserProfile=<elementId>"` (the resolved elementIds from steps 2 and 4). Then call `task-complete(taskId)`.
+6. **Mark step 9 complete.** Call `onboarding-complete-step` with step 9.
+
+After step 9 completes in personal mode, tell the user that {{productName}} is configured for personal use — their employer (if any) is not registered here. If they later become the operator for a business of their own, they can ask {{productName}} to set up a business profile, which invokes the `business-profile` skill directly.
+
+**Post-onboarding work-preference elicitation — no step-9 change.** After step 9 completes, the per-turn `## About the Owner` block surfaces the field-level Coverage signal as the canonical post-onboarding elicitation source: `### Coverage / Missing: communication.preferredChannel, scheduling.workdayStartTime, …`. Onboarding deliberately does NOT pre-elicit these in a questionnaire — the agent drips them organically, one per turn, via the IDENTITY.md § Conversational Memory contract. Step 9's role is to bootstrap identity + persona; work-preferences are accumulated through normal conversation thereafter, with `notApplicable: true` covering the "doesn't apply to me" case (declined fields stop re-prompting).
+
+If the user declines to bootstrap during step 9 in any mode, leave step 9 incomplete AND call `task-update(taskId, status:"failed", errorMessage:"<one-line reason>")` so the action record reflects the abandonment instead of dangling in `running` forever. The next session will resume here with a fresh `task-create` (the prior failed Task stays in the graph as the audit record). Any attempt to write user-domain data will surface `Write blocked (no-admin-user)` or `Write blocked (no-local-business)`, pulling the agent back into this step.

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

@@ -0,0 +1,105 @@
+---
+name: plainly
+description: Use when the user asks for a "plain English" explanation, definition, or summary of a technical concept, or pre-empts one ("explain in plain English", "what does X mean", "define X"). Enforces the recursive plain-English rule: an explanation cannot itself contain terms that need their own explanation.
+---
+
+# plainly
+
+**Scope — agent-to-human only.** Plainly applies to prose returned to a human reader (the operator, a customer, the admin agent when admin renders prose to the operator). It does NOT apply to arguments passed to `image-generate`, `memory-write`, `memory-classify`, `memory-ingest`, `cypher-shell`, or any other MCP tool — those are agent-to-machine payloads where technical descriptors and structured tokens are required, not jargon to strip.
+
+Produce an explanation that *teaches* the concept to a reader who is bright and motivated but **new to the topic**. They hold general vocabulary (integrals, polynomials, bell curves, logarithms) but do not own the specialist machinery (quadrature rules, weight functions, exactness orders, regime generators). Every phrase in the explanation must be one such a reader can either already understand or be brought up to speed on within the explanation itself. Plain English is the **spoken register**: a sentence has to parse if you read it aloud, in conversation, without a whiteboard. The goal is working understanding the reader can apply and pass on, not a textbook entry they could find in a glossary. Hit the bar on the first attempt; iteration is a leak.
+
+## Why this matters
+
+Textbook explanations are technically correct and pedagogically poor. They convey content without producing understanding. Motivated readers can spend decades asking textbook authors, professors, and field experts for an explanation of a concept and never get one that lands, because every explanation hits the technically-correct mark while missing the spoken-register one. /plainly exists to break that cycle, so the reader walks away able to teach the concept to someone else and have *them* understand it too. Two tests every output has to pass:
+
+- **The aloud test**: could you say this in spoken conversation, without a whiteboard or paper? Formulas, Greek letters, parenthetical acronyms, and chained sub-clauses fail this test even amongst specialists. "S-zero times exp of mu times T" is what nobody actually says; "today's price grown at the long-run drift" is what everyone says.
+- **The understanding test**: does the reader walk away able to *apply* the concept, not just recite its definition? An etymological definition ("lognormal = log is normal") often fails this test because it leaves the reader knowing the words but not the implications. The cure is to follow the definition with practical consequences, visual intuition, and contextual significance.
+- **The new-to-topic test**: would a reader new to this specialist area understand every phrase used in the explanation? Specialist phrases ("exact for a polynomial family", "weighted by the normal density", "regime-coupling generator") may be technically correct and even concise, but if they require prior fluency with the topic they fail. The cure is either to define the phrase operationally inside the explanation, or to unpack it into the plain statement of what it actually means in this case.
+
+Failing the aloud test produces opacity; failing the understanding test produces parroting; failing the new-to-topic test produces *appearance of clarity*: the answer reads as crisp to the writer but lands as a wall of jargon to the audience. A reader who can teach the concept onward to someone else has cleared all three.
+
+## The recursive rule (load-bearing)
+
+A plain-English explanation **cannot itself contain terms that need explanation**. Reject any candidate sentence that contains:
+
+- **Acronyms** (PIDE, SDE, ODE, RNG, etc.), even in parentheses. Either expand or replace with the concept the acronym names.
+- **Metaphors that approximate a precise word**: "stitching" for *adding up*, "rule" for *equation*, "chunking" for *grouping*. The precise word is usually also the plain-English word; pick it.
+- **Words whose everyday connotation distorts the meaning**: "increment" connotes positive (use *change*); "step" connotes discrete (use *infinitesimal change* if continuous); "decay" connotes irreversible (use *decrease* if reversible).
+- **Technical terms with a plain-English substitute**: "stochastic" becomes *random*; "deterministic" becomes *fixed by the inputs*; "monotonic" becomes *always moving in one direction*.
+- **Mathematical notation and formulas**: `E^P[S_T] = S_0·exp(μ·T)`, `Σⱼ λᵢⱼ E[Yᵢⱼ]`, function-signature notation like `V(S, t)`, state-tuple notation like `(S, v)`, set-builder notation like `k ∈ {1..K}`, etc. Plain English is the *spoken* register: a sentence has to parse if you read it aloud. "S-zero times exp of mu times T" fails that test even for a quant audience, and so does "V of S comma t" or "k in one to K". Express every relationship in words: "today's price grown at the long-run drift", "option value as a function of spot price and time", "regime index running from one to K". You may *anchor* a single symbol once for cross-reference to the surrounding document (e.g. "the logarithm of S_T, denoted log(S_T)"), but never reproduce a formula, a function signature, or a tuple of state variables. If a relationship genuinely cannot be put into words, the concept is outside the scope of /plainly; see "When NOT to use".
+
+A compound term whose parts are individually plain survives the rule **only if its meaning is compositional**, i.e. the compound means what its parts mean together. *"Differential equation"*, *"random process"*, *"probability distribution"* all survive: a reader who knows what each individual word means can derive the compound's meaning from the parts. *"Characteristic function"*, *"moment generating function"*, *"principal component"*, *"regular expression"* do *not*: each is made of plain English words, but the technical meaning is not derivable from the parts. The mathematical "characteristic function" is the Fourier transform of a probability density; there is nothing in the words "characteristic" and "function" that tells the reader this. Such non-compositional compounds are jargon even when every individual word is plain, and must be either unpacked into their actual meaning or replaced with a more direct phrase. An acronym or coined metaphor is also jargon. **Technical vocabulary already in active use in the surrounding document is fair game**: readers of a quant doc own "logarithm", "normally distributed", "variance", etc.; refusing to use those words and substituting circumlocutions is its own kind of leak.
+
+## Output contract
+
+Plain English isn't only a vocabulary constraint; it's a completeness requirement. A reader needs the *precise definition* AND enough scaffolding to integrate the concept into the surrounding text. The full template:
+
+1. **Definition with explicit notation**: name the precise concept, anchored to the symbol notation the document uses (e.g. *"the logarithm of S_T, denoted log(S_T), is normally distributed"*).
+2. **Practical consequences**: what follows from the definition that the reader can act on or expect (e.g. *"S_T is always positive; large upward moves are more likely than relative downward moves"*).
+3. **(when applicable) Visual intuition**: let the reader picture the thing (e.g. *"the distribution is skewed to the right, with a long right tail"*).
+4. **(when applicable) Contextual significance**: why does the surrounding document care about this property (e.g. *"this is why Black-Scholes is closed-form"*).
+
+Length is dictated by the concept's richness AND by what the user has already supplied. A primitive operation ("what is integration") may need only items 1 and 2, two sentences total. A richer concept ("what is lognormal") usually needs all four. Three or four sentences is the right size for richer concepts; padding beyond that with filler is failure.
+
+**When the user's question is itself a substantive framing, a paragraph that already establishes the definition, motivation, or informal picture and asks for refinement, the answer's word budget is bounded by what makes the explanation land for a reader new to the topic, *not* by the framing's word count.** If the framing is itself written in researcher shorthand (compressing several specialist concepts into a phrase like "exact for a polynomial family"), the answer needs more words to bridge for a new reader. The framing's compactness is not a contract with the audience. The order of priority is: (1) the new-to-topic test must pass; (2) within that constraint, be as concise as possible; (3) only then is the framing a length cap, and only when the framing was already audience-appropriate. A response that runs longer than the prompt is *not* a failure if the extra words are doing bridging work the framing skipped. A response that runs longer than the prompt while *re-stating* what the framing already had IS a failure. The four-item template is still a *maximum*, not a minimum: items the user has already worked out for the right audience are out of scope; items the user only worked out for themselves still need to be done for the reader.
+
+## Rules
+
+- **One precision pass before output.** Read the candidate. Reject if any acronym, metaphor, connotation-distorting word, or unjustified jargon survives.
+- **Separate operation from output.** The operation is one thing; the character of its output (random vs fixed, scalar vs distribution) is a property of the input. Don't conflate them.
+- **No filler.** No "essentially", "basically", "in some sense", "appears to". The explanation is correct or it isn't.
+- **No follow-up offers.** End on the definition.
+- **Strip AI tells.** See the AI-tells catalogue below. Plain English is the *spoken* register, which rules out patterns that AI writing reaches for but humans rarely use in conversation.
+
+## AI tells to strip
+
+These are patterns common in AI-generated prose but rare in actual human writing, especially in spoken or conversational registers. Strip every one on the precision pass. The list grows as more patterns are surfaced.
+
+- **Em-dashes anywhere.** AI reaches for em-dashes constantly; humans use commas, parentheses, semicolons, colons, or just two sentences. "The variance — which mean-reverts to θ — is …" reads as AI; "The variance, which mean-reverts to θ, is …" reads as human. The previous version of this rule allowed em-dashes for "strong breaks" (true asides interrupting the sentence's flow). That carve-out turned out to be the writer's instinct rationalising past the discipline: every em-dash got justified as a strong break, and the polished output kept reading as AI. There is no exception. Use a comma, a semicolon, a colon, parentheses, or two sentences. Never an em-dash, including for heading-then-description separators in marketing copy (use a colon, a comma, or hyphen-with-spaces). The skill's own historical examples in `references/worked-examples.md` contain em-dashes inside quoted bad-pattern illustrations; those stay as illustrations, but the rule applies to every polished output and to the skill's own instructional prose going forward.
+- **Antithetical parallelism: "it's not X, it's Y" / "this isn't X — it's Y".** AI loves this construction as a rhetorical flourish. Humans usually just say "it's Y" and skip the negation, or use "X is wrong; Y is closer to right" if the contrast genuinely matters. Watch especially for it in opening sentences.
+- **Greek letters as primary referents *and* as back-references.** σ, η, θ, ν, etc. as the leading term in a phrase ("vol-of-VIX η_i", "constant-σ model") OR as a later standalone reference ("only the source of η changes"). The plain-English term should be used **throughout**: lead with the meaning ("vol-of-VIX", "constant-volatility model"), use the symbol parenthetically once for cross-reference to the surrounding doc (e.g. "vol-of-VIX (η_i)"), and never back-reference the bare symbol on its own thereafter. Greek letters carry visual jargon weight even when "established" in the doc's glossary; a reader who doesn't recognise the letter (eta? n? a special character?) has to decode it on every appearance, including after it was anchored, because mapping "η here = vol-of-VIX from a sentence ago" is itself the cognitive cost the parenthetical anchor was meant to remove. The word and the letter's spoken name are roughly the same length, so brevity isn't a trade-off either way.
+- **Parenthetical clarifications that introduce more jargon than they remove.** "(a chain-rule shortcut on the Heston dynamics)" attempts to explain a formula but brings in "chain-rule" (a calculus term the reader may not own) without making the formula itself any plainer. If a clarification would itself need a clarification, drop it. The reader can pick up "this is approximate" from broader context (a surrounding sentence about closed-form approximations, etc.) without that specific aside.
+- **Casual-register words: "recipe", "trick", "vibe", "bake in", "secret sauce".** These borrow tone from cooking or colloquial registers and read as glib in technical writing. Use neutral equivalents (*method*, *technique*, *approach*, *embed*) that match the document's register.
+- **Proper-noun mathematician names used as primary referents.** "Fourier methods", "Carr-Madan technique", "Heston-style closure", "Black-76 lognormal price": the proper noun names the inventor or the canonical paper, not the operation itself. A new-to-topic reader does not need to know who Fourier was to understand a transformation. Drop the proper noun and name the operation directly ("a transformation", "a closed-form pricing approach", "a lognormal-on-forward price"). Keep the proper noun only where it is genuinely load-bearing as a citation the reader might look up.
+- **Placeholder words: "methods", "techniques", "approaches".** Noun-phrase fillers that name the *category* of an operation without naming the operation. "Fourier methods" becomes "a transformation"; "an approximation method" becomes "an approximation"; "a numerical technique" becomes the named technique if you can. They give the appearance of substance without delivering any. The category is the right level of abstraction only rarely; check before using.
+- **Stacked-modifier noun phrases.** "The integrated CIR variance distribution" stacks three modifiers ("integrated", "CIR", "variance") onto one noun ("distribution"). A new-to-topic reader cannot parse three modifiers in sequence reliably. Unstack: "the variance probability distribution", "the distribution of variance over time". Each modifier you keep should earn its place by adding precision the reader needs at that point.
+- **Elaborate phrasing for plain claims.** "Match shape to negligible practical error" is a four-word phrase that says what "are close enough" says in two. When the elaborate version doesn't add precision the reader needs, use the plain version. Watch for the construction in particular: any technical-feeling verb-noun pair ("preserve fidelity", "exhibit convergence", "match topology") deserves a precision-pass check against its plain alternative.
+- **Implicit contrasts the reader has to infer.** A source like "X would require expensive method A; the approximations match shape closely enough" contains an implicit "but": the second clause is offered *instead of* the first. Plain English makes the contrast explicit ("would require A *but* the approximations *we use instead* are close enough"). Don't assume the reader will reconstruct the rhetorical relationship from punctuation.
+- **TED-style or formulaic openers.** "In today's fast-paced world…", "In the ever-evolving landscape of…", "At the heart of…", "In the digital age…", "Imagine a world where…", "As we move forward…", "It's no secret that…". Boilerplate intro scaffolding that warms up the reader without saying anything. The sentence *after* the opener is almost always the real first sentence; delete the opener and start there.
+- **Inflation vocabulary.** Words that imply a magnitude, novelty, or significance the surrounding writing hasn't earned. The verb/adjective list: *leverage* (use), *unlock*/*unleash* (allow, enable), *synergy*, *paradigm shift*, *cutting-edge*, *robust*, *scalable*, *comprehensive* (complete), *myriad*/*plethora* (many), *pivotal* (important), *unwavering*, *multifaceted*, *transformative*, *revolutionary*, *game-changer*/*game-changing*, *next-level*, *must-read*, *impactful*, *powerful*, *meaningful*, *strategic*, *seamless*, *holistic*, *testament*. The metaphor list: *tapestry*, *beacon*, *symphony*, *journey*, *roadmap*, *landscape* used non-literally. The honorific list: *titans*, *architects*, *visionaries*, *thought leaders* used as titles. Replace each with the concrete verb, noun, or property the writing is actually claiming: "cuts query time in half" beats "powerful"; "use" beats "leverage"; "many" beats "myriad".
+- **Filler transitions and hedge openers.** Paragraphs that open with *Furthermore*, *Moreover*, *Additionally*; sentences that open with *It is important to note that…*, *It's worth noting that…*, *Keep in mind that…*, *It should be mentioned that…*. Conversational humans don't open this way; the next clause is always the actual content. Cut the opener; the sentence still works.
+- **Rhetorical lecture banter.** "What does this mean?", "What can we learn from this?", "Why does this matter?", "Let's break this down", "Let's dive in", "Let's unpack this". Borrowed from webinar/TED-talk register, designed to *sound* engaging without being so. State the point directly instead. Especially suspicious in casual or non-instructional text where there is no audience to address.
+- **Parallel-pattern overuse, especially "not only X, but also Y".** Beyond the antithetical "it's not X, it's Y" already listed: matching sentence shapes across multiple consecutive lines ("X does A. Y does B. Z does C."), and *not only … but also …* repeated as a flourish. Vary sentence shape; use plain "and", or just two sentences, when no real contrast is being drawn.
+- **Signposting in narrative prose.** "In this section, we'll explore…", "Next, we'll turn to…", "To wrap up…", "Before we dive in…", and "First … Second … Third …" patterns in passages where the structure isn't naturally enumerated. Headings already signpost; doing it again in prose is meta-narration. Cut the scaffolding and let the content speak.
+- **Conceptual emotion without grounding.** "Success can be fulfilling", "the team felt proud", "it was a rewarding experience": emotions named at the level of category with no sensory, bodily, or situational detail. Either ground the feeling in something concrete (what specifically happened, the small awkward moment, the room) or drop it. Naming an emotion isn't evoking it.
+- **Citation-shaped fillers without sources.** "Studies show…", "Research indicates…", "Experts agree…", and round-number statistics ("90% of users…", "3× more effective") with no named source or link. Either name the study, expert, or source so the reader can verify, or drop the appeal to authority and let the claim stand on its own.
+- **Gratuitous emojis, bold, italics, and exclamation marks.** Outside genuinely commercial or chat-app contexts: emojis sprinkled through technical prose, bold or italic emphasis on every other phrase, exclamation marks added to *sound* enthusiastic. These are AI defaults, not human ones. Reserve bold/italic for places a scanning reader truly needs the visual cue; use exclamation marks only when something is actually exclaimed.
+- **Uniform sentence length and cadence.** AI prose settles into 12-18-word sentences at a steady rhythm; human prose alternates: a 30-word sentence can be followed by a 4-word one. If three consecutive sentences are within ~3 words of each other, vary at least one (split a long one, fuse two short ones). The texture is itself a tell, even when every word is fine on its own.
+- **Format scaffolding (bold headings, em-dash separators, parallel bullet stacks) in marketing copy.** Bold-tag headings followed by em-dash separators followed by stacked one-liners read as AI marketing-page output even when every individual word is plain. In human-facing copy, prose with conversational lead-verbs almost always does the same job better. See worked example 12 for the canonical case.
+- *(Add more as you find them.)*
+
+## When NOT to use
+
+- The user wants a tutorial, derivation, or worked example: that is teaching, not defining.
+- The user wants a formal mathematical definition with notation: that is the opposite of plain English.
+- The concept has no plain-English form that survives precision (some objects only exist in their formal language). Say so in one sentence and stop.
+
+## Worked examples
+
+Twelve worked examples are kept in [`references/worked-examples.md`](references/worked-examples.md), loaded on demand. The examples cover, in order:
+
+1. Integration: a primitive operation, two-sentence definition.
+2. "S_T is lognormal": a richer concept that uses all four template items.
+3. The Merton model dimensionality question: function-signature notation is itself a formula.
+4. Quadrature, well-framed: density beats scaffolding when the framing is already audience-appropriate.
+5. Quadrature, new reader: precision without bridging fails the new-to-topic test.
+6. Quadrature, in-document phrasing: scope-matching, the operational definition is often enough.
+7. "parameter standard errors fall out of the calibrated Jacobian": one sentence in, one sentence out (transliterate, don't expand).
+8. "V_0 memory has decayed to θ": symbol anchoring (meaning first, symbol parenthetical).
+9. VIX options under regime-switching Heston: Greek letters are jargon, parenthetical clarifications must add substance, watch the register.
+10. "Same closure as the constant-σ path": "same as X" references must define X, not punt to it.
+11. VIX pricing under Heston: when in doubt, go simpler, the audience is less experienced than the writer thinks.
+12. Marketing-pitch format scaffolding: bold-headings-with-em-dashes is itself the AI tell, regardless of how plain the words inside are.
+
+Read the relevant example before producing a polish in a similar register. The principles in this file are the load-bearing rules; the examples are the concrete demonstrations of each one.