@rubytech/create-realagent-code 0.1.30 → 0.1.32

package/payload/platform/plugins/admin/hooks/onboarding-skill-drift.sh

@@ -1,102 +0,0 @@
-#!/usr/bin/env bash
-# Task 063 / Task 049. Stop-event hook that flags admin agent onboarding
-# drift on the native Claude Code (PTY) surface. Post-Task-049 there is no
-# `render-component` tool, so the contract is no longer "called render-component";
-# it is "the assistant ends its turn on a prompt the operator can answer".
-#
-# Behaviour:
-#   1. Read transcript_path from the Stop event JSON on stdin.
-#   2. Walk the JSONL backwards. Find the most recent user event whose
-#      `message.content` contains the literal `<onboarding-state ` marker.
-#   3. If no such user event exists in this transcript, fail-open (exit 0).
-#   4. Otherwise, find the most recent assistant event after that injection.
-#      Count assistant turns since the injection so the log line carries a turn number.
-#   5. Evaluate the ends-with-prompt contract on the assistant text:
-#        - PASS when the last non-whitespace character is `?`, OR
-#        - PASS when the trailing block (last ~8 lines) contains a numbered
-#          or bulleted list item (`1. `, `2) `, `- `, `* `).
-#        - FAIL otherwise.
-#   6. Emit `[onboarding-skill-drift] turn=<N> contract=ends-with-prompt
-#      result=<pass|fail> reason=<reason>` on stderr.
-#
-# Exit 0 always: this hook is observation, not enforcement. Infrastructure
-# failures (jq missing, transcript unreadable) also exit 0 so a hook bug
-# never blocks the agent's response.
-
-set -uo pipefail
-LOG_TAG="[onboarding-skill-drift]"
-
-if ! command -v jq >/dev/null 2>&1; then
-  echo "$LOG_TAG turn=0 contract=ends-with-prompt result=skip reason=jq-missing" >&2
-  exit 0
-fi
-
-INPUT=$(cat 2>/dev/null || echo '{}')
-TRANSCRIPT=$(echo "$INPUT" | jq -r '.transcript_path // empty' 2>/dev/null)
-if [ -z "$TRANSCRIPT" ] || [ ! -f "$TRANSCRIPT" ]; then
-  echo "$LOG_TAG turn=0 contract=ends-with-prompt result=skip reason=no-transcript" >&2
-  exit 0
-fi
-
-# Locate the most recent <onboarding-state ...> injection in a user event.
-# The injection block is prepended verbatim to the operator's input on the
-# first /input of an eligible session, so it appears as the leading bytes of
-# the user event's message text. Search backwards for the last one.
-INJECTION_LINE=$(grep -n '<onboarding-state ' "$TRANSCRIPT" 2>/dev/null \
-  | grep '"type":"user"' \
-  | tail -n 1 \
-  | cut -d: -f1)
-
-if [ -z "$INJECTION_LINE" ]; then
-  # No injection in this transcript window. Nothing to evaluate.
-  exit 0
-fi
-
-# Slice the file from just after the injection line.
-TAIL=$(tail -n "+$((INJECTION_LINE + 1))" "$TRANSCRIPT" 2>/dev/null)
-
-# Count assistant turns since the injection and pick the most recent.
-ASSISTANT_TURNS=$(echo "$TAIL" | grep -c '"type":"assistant"')
-ASSISTANT=$(echo "$TAIL" | grep '"type":"assistant"' | tail -n 1)
-
-if [ -z "$ASSISTANT" ]; then
-  echo "$LOG_TAG turn=0 contract=ends-with-prompt result=skip reason=no-assistant-turn" >&2
-  exit 0
-fi
-
-# Concatenated text content (final character matters for the `?` check; final
-# block matters for the enumerated-list check).
-ASSISTANT_TEXT=$(echo "$ASSISTANT" | jq -r '
-  .message.content // []
-  | map(select(.type == "text") | .text)
-  | join("\n")
-' 2>/dev/null)
-
-# Trim trailing whitespace and find the last non-whitespace character.
-TRIMMED=$(echo "$ASSISTANT_TEXT" | sed -E 's/[[:space:]]+$//')
-LAST_CHAR=$(echo -n "$TRIMMED" | tail -c 1)
-
-# Evaluate the ends-with-prompt contract.
-ENDS_WITH_PROMPT=0
-ENDS_WITH_PROMPT_REASON="neither-question-nor-list"
-
-if [ "$LAST_CHAR" = "?" ]; then
-  ENDS_WITH_PROMPT=1
-  ENDS_WITH_PROMPT_REASON="trailing-question-mark"
-else
-  # Take the last 8 lines and look for a numbered/bulleted list item.
-  TRAIL_LINES=$(echo "$TRIMMED" | tail -n 8)
-  if echo "$TRAIL_LINES" | grep -qE '^[[:space:]]*([0-9]+[.)]|[-*])[[:space:]]+'; then
-    ENDS_WITH_PROMPT=1
-    ENDS_WITH_PROMPT_REASON="trailing-enumerated-list"
-  fi
-fi
-
-if [ "$ENDS_WITH_PROMPT" = "1" ]; then
-  echo "$LOG_TAG turn=$ASSISTANT_TURNS contract=ends-with-prompt result=pass reason=$ENDS_WITH_PROMPT_REASON" >&2
-else
-  SAMPLE=$(echo "$TRIMMED" | tail -c 120 | tr '\n' ' ' | sed 's/[[:space:]]\+/ /g')
-  echo "$LOG_TAG turn=$ASSISTANT_TURNS contract=ends-with-prompt result=fail reason=$ENDS_WITH_PROMPT_REASON sample='${SAMPLE}'" >&2
-fi
-
-exit 0

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

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

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

@@ -1,240 +0,0 @@
-# Onboarding
-
-Guided first-run setup for new installations. 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`. Log the resolved resume point at session start: `[onboarding] resume currentStep=<N>`.
-
-The skill describes what each step must collect and which persistence side-effect marks it complete. It does not enumerate tool calls — the `<onboarding-state>` system-prompt directive is the gate, and the host environment supplies the surface (plain chat under native Claude Code). Every step persists by calling `onboarding-complete-step` with the step number once its side-effects have landed; if the session ends, the next session resumes from the right place.
-
-**Turn-completion contract.** Any turn that advances `currentStep` (via `onboarding-complete-step`) OR narrates a step transition ("Moving to step N", "Step N done", "Proceeding to step N") MUST end with the next step's prompt — a question or an enumerated choice list — never a bare prose paragraph. 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 first turn acknowledges AND immediately presents the step-8 prompt without an intervening dead-end paragraph.
-
-**Presentation rules.** Choices are presented as numbered or lettered lists; the operator replies with the number, letter, or name. File content (SOUL, KNOWLEDGE, config) is proposed in a fenced markdown block and only written after the operator approves verbatim or supplies edits. Never use directional words ("above", "below"); name the file or the section.
-
-## Step 1 — Plugin selection
-
-*(skip if `currentStep` >= 1)*
-
-`onboarding-plugin-options` 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.
-
-Extend the array with one Claude Official entry and three Claude Anthropic verticals entries (defaults: not selected — operator picks each deliberately):
-
-- Claude Official: `stripe` — Live access to payment and business data.
-- Claude Anthropic verticals: `kyc-screener` (claude-for-financial-services) — 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`.
-- Claude Anthropic verticals: `meeting-prep-agent` (claude-for-financial-services) — 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`.
-- Claude Anthropic verticals: `pdf-viewer` (knowledge-work-plugins) — 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`.
-
-Present the full combined list to the operator as a numbered list, grouped by category (`{{productName}} plugins`, `Claude Official`, `Claude Anthropic verticals`), with each entry's value, label, and description visible. Note which are locked (core, already active), which are recommended (defaultEnabled), and which are optional. Ask the operator to reply with the numbers or names they want, or `skip` to install none.
-
-Apply the operator's selection:
-
-- For each selected **Claude Official plugin**, run: `claude plugin install <name>@claude-plugins-official`
-- For each selected **Claude Anthropic vertical**, run the install command from the description verbatim:
-  - `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`) — e.g., `docs` not `maxy-guide`. This activates the plugin's behaviour and MCP server from the next session.
-
-Persistence side-effect: `onboarding-complete-step` with step 1, passing `acceptedAnthropicVerticals` and `declinedAnthropicVerticals` derived from the operator's reply against the closed Anthropic-verticals set `{kyc-screener, meeting-prep-agent, pdf-viewer}` — `acceptedAnthropicVerticals` is the intersection, `declinedAnthropicVerticals` is the set minus the intersection. Both arrays must be passed together; this emits the `[plugin-onboarding] group=anthropic-verticals presented=3 accepted=<n> declined=<n>` counter line.
-
-If any {{productName}} plugins were enabled, call `session-reset` immediately after step 1 completes. {{productName}} plugin MCP servers only load when a new subprocess spawns — the current session cannot access them. After reset, the new session resumes from step 2 with all newly enabled plugins available. If no {{productName}} plugins were enabled, 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 can configure WiFi later through conversation.
-
-Check WiFi hardware via the `wifi` tool with `action: "status"`. If the result says "No WiFi hardware detected", tell the operator their device has no WiFi capability and persist step 2 complete; proceed to step 3.
-
-If WiFi hardware is present and already connected with an IP, ask whether to keep the current network or switch. If the operator keeps it, persist step 2 complete.
-
-If WiFi hardware is present but not connected, ask whether the operator wants to connect now. If they decline, persist step 2 complete.
-
-If the operator wants to connect:
-
-1. Run `wifi` with `action: "scan"` to list visible networks.
-2. Present the networks as a numbered list, sorted by signal strength descending, each entry showing SSID, signal strength, and security. Tell the operator they can reply with the number, the SSID, or `Other` if their network does not appear (in which case they supply the SSID by typing it).
-3. Ask for the WiFi password in plain chat.
-4. Run `wifi` with `action: "connect"`, the selected `ssid`, and the `password`.
-5. On success the tool confirms it is safe to unplug ethernet. On failure (wrong password, network not found, no IP), relay the error and ask whether to retry or skip.
-
-Persistence side-effect: `onboarding-complete-step` with step 2 once connected or skipped.
-
-## Step 3 — Output style
-
-*(skip if `currentStep` >= 3)*
-
-Ask the operator which output style they want:
-
-1. `default` — Efficient and task-oriented; concise responses without extra explanation.
-2. `explanatory` — Adds educational insights between steps; great for learning.
-
-Operator replies with the number or value. Call `account-update` with field `outputStyle` and the chosen value. Persistence side-effect: `onboarding-complete-step` with step 3.
-
-## Step 4 — Thinking view
-
-*(skip if `currentStep` >= 4)*
-
-Ask the operator which thinking view they want:
-
-1. `default` — Thinking visible: shows reasoning expanded, collapses tool details.
-2. `expanded` — Everything visible: expands all reasoning and tool details.
-3. `collapsed` — Responses only: collapses all reasoning and tool details.
-
-Operator replies with the number or value. Call `account-update` with field `thinkingView` and the chosen value. Persistence side-effect: `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 `UserProfile` at first login. Confirm it with the operator so scheduling, cron events, and time formatting use the correct locale.
-
-Call `profile-read` to retrieve the current `UserProfile` and extract `timezone`. Present a numbered list: the auto-detected timezone first (described as "Auto-detected from your device"), then common alternatives (`Europe/London — GMT/BST`, `America/New_York — Eastern Time`, `America/Los_Angeles — Pacific Time`), omitting any duplicate of the auto-detected value. Tell the operator they can also reply with their own IANA identifier (e.g. `Asia/Tokyo`).
-
-Call `profile-update` with `profileFields: { timezone: "<selected_value>" }`. Persistence side-effect: `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, read `agents/admin/SOUL.md`. If it already contains actual business content (more than the `# Soul` header), persist step 6 complete and proceed — personalisation is already in place.
-
-If `agents/admin/SOUL.md` is empty or missing content, ask the operator about:
-
-- **Tone and personality** — how the agent should sound (formal, casual, warm, blunt, etc.) and 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, FAQs 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.
-
-Compose the SOUL content in a fenced markdown block in chat. Ask the operator to reply `approve` to write it as-is, `edit` to describe changes, or `replace` to supply their own full content. Iterate until the operator approves, then `Write` the approved content to `agents/admin/SOUL.md`.
-
-Persistence side-effect: `onboarding-complete-step` with step 6 after the file is written and approved.
-
-**Document ingestion.** If the operator 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 persisting step 6 complete — not before. Use the Agent tool with `run_in_background: true`. The critical path (SOUL file, step completion) must not depend on ingestion. The brief includes the document path, the document subject (typically the account-owner's `UserProfile` or the `LocalBusiness` depending on the doc), and the scope. If no documents were uploaded, skip.
-
-**Next steps message.** After step 6 completes, tell the operator that everything configured during onboarding — plugins, WiFi, output style, thinking view, timezone, and personality — can be changed at any time through conversation. Then present three optional next things (all available whenever the operator is ready):
-
-1. **Set up remote access** — Cloudflare Tunnel connects the platform to a custom domain so the operator and their customers can reach it from anywhere.
-2. **Set up the public-facing agent** — an Anthropic API key lets visitors chat with the business.
-3. **Capture the business profile** — identity, address, hours, services, FAQs. Populates the graph so the agent can answer business questions and public-facing customers get accurate information.
-
-Ask which (if any) the operator wants to start with. Step 7 covers remote access; step 8 covers the API key; step 9 covers persona and profile.
-
-## 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 operator: would they like to set up remote access now? Cloudflare connects the platform to a custom domain so the operator and their customers can reach it from anywhere. They need a Cloudflare account and a domain; if they don't have these yet, the skill walks them through it.
-
-If the operator declines, tell them remote access is still possible without Cloudflare — WhatsApp, Telegram, and Email channels connect directly to the device, so the operator and their customers can reach the agent through those channels without a tunnel. Persistence side-effect: `onboarding-complete-step` with step 7.
-
-If the operator wants to proceed, confirm the domain state in one sentence: is their 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" verbatim and wait for the operator to confirm the zone shows **Active**.
-
-Then collect the FQDNs and password in plain chat:
-
-- **Admin FQDN** (required) — e.g. `admin.example.com`. This is where the operator signs in.
-- **Public FQDN** (optional) — e.g. `public.example.com` or `chat.example.com`. Where visitors reach the public-facing agent.
-- **Apex FQDN** (optional) — e.g. `example.com`. The bare domain; apex hostnames cannot be routed by the Cloudflare CLI and the script will print an `ACTION REQUIRED` dashboard step for them.
-- **Admin password** — the password the operator will use to sign in remotely. Validated against the platform's password-strength rules; if it fails, relay the requirements and re-ask.
-
-Resolve `brand` and `port` deterministically from the runtime environment (brand identity has no authority over what zones the operator's Cloudflare account holds; do not read `brand.json` for domain options). Then:
-
-1. Set the admin password via `POST /api/remote-auth/set-password` on localhost. If this fails, halt and relay the error — do not proceed to the tunnel script. The script's post-restart verification curls the admin hostname and fails if remote-auth is not configured.
-2. On password-set success, run `~/setup-tunnel.sh <brand> <port> <admin-fqdn> [<public-fqdn>] [<apex-fqdn>]` via Bash. The script handles cloudflared OAuth login (spawning a browser on the brand's VNC display for the operator to click Authorize), tunnel creation, DNS routing for each subdomain, `config.yml` + `tunnel.state`, and dispatches the brand-service restart on a transient `systemd-run` unit. The chat UI receives a `server_shutdown` SSE frame and reconnects.
-3. For each submitted hostname that is not the admin FQDN and does not start with `public.`, append it to `~/{configDir}/alias-domains.json` so `isPublicHost()` classifies it as public.
-4. Relay the script's stdout/stderr verbatim. Quote any `ACTION REQUIRED` block exactly — the operator needs the specific dashboard instruction.
-
-When the script exits zero, step-7 completion has already been persisted by the script itself (`setup-tunnel.sh:503`'s onboarding-persist branch). Do not call `onboarding-complete-step` with step 7 — any call after the script's restart dispatch would race the service restart and almost always lose.
-
-When the script exits non-zero, relay the output, name the exit code, and cite `plugins/cloudflare/references/reset-guide.md` for recovery. Offer to retry after any manual steps the error named. Do not synthesise alternative recovery commands; do not attempt a different `cloudflared` flag combination; do not call the Cloudflare API or SDK from any language. The Cloudflare tool-discipline rules in `plugins/cloudflare/skills/setup-tunnel/SKILL.md` apply.
-
-**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 the admin agent's view is identical.
-
-By the time the marker arrives, `OnboardingState.currentStep` is already 7 (the script's filesystem flag was consumed by `consumeStep7FlagUI` on the way in). The operator's message at `currentStep=7` is the agent's single source of truth that step 7 finished cleanly; the script's flag-consume is the orthogonal proof that the state machine advanced. Acknowledge the marker, then present the step-8 prompt in the same turn — do NOT re-ask the Cloudflare question, do NOT re-collect FQDNs, do NOT call `onboarding-complete-step` with step 7 (already done).
-
-## 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.
-
-Call `anthropic-setup` with no arguments and branch on its status:
-
-- `complete` — the key is already stored and working. Persistence side-effect: `onboarding-complete-step` with step 8.
-- `not_needed` — no public-facing endpoint is configured (the operator skipped step 7 or completed it without a public hostname). Relay the tool's `message` verbatim and persist step 8 complete. Do not prompt to set up the key; there is nothing for it to power yet.
-- `awaiting_signin` — no stored key. Ask whether the operator wants to set up the API key now. If they decline, tell them they can ask later and persist step 8 complete.
-- `error` — relay the message and ask whether to retry or skip.
-
-If the operator wants to proceed from `awaiting_signin`, the tool returned a `url` and an `action` in `data`. Tell the operator: this is the Anthropic Console (`platform.claude.com`), a separate service from the Claude account already signed in — Anthropic keeps the two as independent services with separate sessions and billing, even though the same credentials work on both. Ask the operator to open the URL in a browser and sign in.
-
-When the operator confirms they have signed in, run the `action` from the tool's response via the standard browser-evaluate tool call (the chrome-devtools or playwright MCP exposes `browser_evaluate`; pass the JavaScript expression from `data.action.params.function`). Take the string result and call `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 operator to sign in at the Console; when they confirm, run the new `action` via `browser_evaluate`, pass the result back as `consoleResult`, handle the status again.
-- `awaiting_credits` — operator 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 operator confirms credits added, run the new `action`, pass the result back, handle again.
-- `complete` — persistence side-effect: `onboarding-complete-step` with step 8.
-- `error` — relay the message; ask whether to retry 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 0 (the public-endpoint gate) and re-checks the stored key unnecessarily.
-
-Do not read any other skill files; do not call any other Anthropic tools; 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 the question is surfaced 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.
-
-**Ask the persona question first.** Present two choices:
-
-1. `personal` — Just for me. I am not setting this up for a business; {{productName}} is my personal operations agent.
-2. `business-owner` — For my business. I am the owner / operator and {{productName}} is the operations agent for my company.
-
-The operator replies with the number, the value, or the label. If the reply is anything other than one of the two documented modes (free text, "Other", "both", off-topic), answer the off-topic part briefly if relevant, then re-present the same two-choice question. Do not improvise a third path; step 9 stays incomplete until the operator picks one of the two modes.
-
-**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`: one-line summary describing the chosen mode and what entities will be produced
-- `status`: `"running"`
-- `kind`: `"onboarding-establish-owner"`
-- `inputsProvided`: the keys passed 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 is collected.** The `onboarding-establish-owner` Task is the audit record for step 9. Record every operator-meaningful fact via 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 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 threads 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 operator provides. When `business-profile` reports that the required nodes exist, 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`). Call `task-complete(taskId)`. Persistence side-effect: `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.** Ask in one short conversational message what feels natural to volunteer at first contact — identity (email, phone, names), context (where they live, languages they speak, what they do, who they work for), or anything else the operator wants to share. The personal-profile Person is comprehensive, not enumerated: accept whatever the operator offers, do not chase a fixed list. The operator 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). Call `task-complete(taskId)`.
-6. **Persistence side-effect:** `onboarding-complete-step` with step 9.
-
-After step 9 completes in personal mode, tell the operator 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 operator 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 resumes 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.