@rubytech/create-maxy-code 0.1.23 → 0.1.26

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

@@ -1,105 +1,95 @@
 # 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`.
+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>`.
 
-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.
+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.
 
-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 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.
 
-**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.
+**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)*
 
-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.
+`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.
 
-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" }`.
+Extend the array with one Claude Official entry and three Claude Anthropic verticals entries (defaults: not selected — operator picks each deliberately):
 
-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:
+- 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`.
 
-- `{ 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" }`
+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.
 
-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.
+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 quoted verbatim in that entry's description:
+- 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`) as the plugin name — e.g., `docs` not `maxy-guide`. This activates the plugin's behaviour and MCP server from the next session.
+- 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.
 
-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.
+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 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.
+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 who prefer a wired connection can skip and set up WiFi later through conversation at any time.
+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.
 
-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.
+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, 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 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: "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 WiFi hardware is present but not connected, ask whether the operator wants to connect now. If they decline, persist step 2 complete.
 
-If the user wants to proceed:
+If the operator wants to connect:
 
-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.
+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.
 
-After the WiFi is connected (or the user skips), call `onboarding-complete-step` with step 2.
+Persistence side-effect: `onboarding-complete-step` with step 2 once connected or skipped.
 
 ## 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:
+Ask the operator which output style they want:
 
-- `{ 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." }`
+1. `default` — Efficient and task-oriented; concise responses without extra explanation.
+2. `explanatory` — 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.
+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)*
 
-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:
+Ask the operator which thinking view they want:
 
-- `{ 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." }`
+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.
 
-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.
+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 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" }`
+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.
 
-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`).
+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`).
 
-After the user confirms or selects a timezone, call `profile-update` with `profileFields: { timezone: "<selected_value>" }`. Call `onboarding-complete-step` with step 5.
+Call `profile-update` with `profileFields: { timezone: "<selected_value>" }`. Persistence side-effect: `onboarding-complete-step` with step 5.
 
 ## Step 6 — Admin personality
 
@@ -107,149 +97,144 @@ After the user confirms or selects a timezone, call `profile-update` with `profi
 
 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.
+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 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:
+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.), language preferences
-- Working style: how the agent should collaborate — proactive vs. wait-for-instruction, terse vs. explanatory, how to handle uncertainty
+- **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, 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.
+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.
 
-SOUL contains tone, language, working style, and the agent's role within the business — factual business data lives in the graph, not here.
+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`.
 
-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.
+Persistence side-effect: `onboarding-complete-step` with step 6 after the file is written and approved.
 
-After the admin SOUL is written and approved, call `onboarding-complete-step` with step 6.
+**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.
 
-**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 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):
 
-**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 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.
 
-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.
+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.
+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."
+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 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 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 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**.
+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 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.
+Then collect the FQDNs and password in plain chat:
 
-```
-{
-  title: "Set up remote access",
-  description: "Connect your device to a custom domain.",
-  submitLabel: "Set up Cloudflare"
-}
-```
+- **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.
 
-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.
+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 your view as the admin agent is identical.
+- **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 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.
+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 — the user can skip it and set up the API key at any time through conversation.
+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. If it returns `complete`, the key is already stored and working — call `onboarding-complete-step` with step 8 and skip ahead.
+Call `anthropic-setup` with no arguments and branch on its status:
 
-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.
+- `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 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 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.
 
-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.
+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:
 
-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.
+- `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.
 
-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`:
+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.
 
-- `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.
+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 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.
+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`: a one-line summary describing the chosen mode and what entities will be produced
+- `description`: 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
+- `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 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.
+**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 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.
+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`:
+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.
+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). Then call `task-complete(taskId)`.
-6. **Mark step 9 complete.** Call `onboarding-complete-step` with step 9.
+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 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.
+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 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.
+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.

package/payload/platform/plugins/admin/skills/session-management/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: session-management
+description: "Reset the current session, list past sessions, continue a previous session, or read the session memory. Triggers when the owner says 'start a new session', 'continue the last session', 'pick up where we left off', 'what were we doing last time', or asks about session state."
+---
+
+# Session management
+
+This skill wraps the session tools and carries the discipline that keeps long-running work coherent across sessions. The platform handles a lot of session machinery automatically: this skill is for the moments where the owner names a session intent directly.
+
+## The tools
+
+| Tool | Purpose |
+|---|---|
+| `session-reset` | Clear the current session and return to idle. |
+| `session-list` | List recent sessions with metadata. |
+| `session-resume` | Resume a specific session by `conversationId`. |
+| `session-compact-status` | Read the compaction state of the current session: how much context has been compacted, what remains. |
+
+## Resetting the session
+
+When the owner asks to start a new session, clear the conversation, or reset, call `session-reset`. Do not ask for confirmation. After the tool call, say nothing further; the UI clears and returns to idle.
+
+**Before suggesting a reset (e.g. after a plugin activation, when context has drifted), persist every actionable finding from the current conversation to its durable store first.** Compaction saves a session summary, but summaries are lossy: decisions, working state, and unfinished threads must be captured explicitly before the context window is cleared. Write open tasks via `task-create`, profile updates via `profile-update`, and any other graph state. Then tell the owner what will carry into the new session (the summary and the open tasks via `<previous-context>`) and suggest the reset.
+
+## Continuing a previous session
+
+When the owner asks to continue, pick up, resume, or carry on:
+
+- **Most recent session.** Call `session-list` with `limit: 1`, then `session-resume` with the returned `conversationId`.
+- **Specific session by name or topic.** Call `session-list` with a higher limit, identify the matching session, then `session-resume`.
+- **No sessions found.** Tell the owner. Do not improvise by reading `<previous-context>`, searching memory, or re-researching prior work.
+
+## Trusting the session summary
+
+When `<previous-context>` is present in the system prompt, the platform has injected a recent session summary and the open tasks at session end. The platform rejects stale summaries older than 48 hours; when the summary is present, it is recent and trustworthy.
+
+- Trust the summary for state orientation. Do not re-verify claims it already describes.
+- Pick up from the state the summary describes. Redundant `memory-search` or other tool calls for information already in the summary waste the owner's time.
+- Use the summary to greet the owner with awareness of prior work and outstanding tasks.
+
+When `<previous-context>` is absent, Neo4j was unreachable or no prior context exists: proceed normally, using tool calls to establish state.
+
+## The recovery context block
+
+A `<recovery-context>` block on the user-message side appears whenever the previous turn was aborted by a stall recovery. It is the authoritative description of what failed, what was incomplete, and what to do now.
+
+- The **resume variant** announces that a synthetic tool result for the in-flight `tool_use_id` was just pushed above this message. Read it for the completed-work summary, then resume by re-issuing the next pending step concretely.
+- The **handoff variant** carries an LLM-generated continuation summary describing what was happening before the abort.
+
+In both shapes, the next operator message means resume the work. Never treat it as empty, never ask "what would you like to do?", never wait for direction. Do not re-research the blocker. Do not call `session-list` to figure out what was happening.
+
+## The api-wait-ping liveness gate
+
+The platform suppresses a heartbeat-driven stall fire while the SDK API request is still alive, bounded by a 600-second cap. When the cap forces an abort, the synthetic tool result names "API request stayed alive past the 600 s cap without producing tokens". This is upstream API latency, not specialist failure. Do not infer that the specialist's approach was wrong from a long stall; many stalls are not the subagent's fault.
+
+## In managed context mode
+
+Conversation history is provided inside `<conversation-history>` tags. Use `session-compact-status` to retrieve older archived context if needed.
+
+## What this skill does not do
+
+It does not edit summaries, delete past sessions, or modify the recovery-context block. These are platform-owned mechanics.

package/payload/platform/plugins/cloudflare/references/dashboard-guide.md

@@ -103,6 +103,43 @@ Use this when you need to audit which hostnames are pointing at which `<UUID>.cf
 
 ---
 
+## Author an Access policy for SSH or SMB (Task 009)
+
+When `setup-tunnel.sh` adds an SSH or SMB ingress hostname, it prints an
+`ACTION REQUIRED` block naming this click-path. The script does NOT
+create the Access policy — Cloudflare API/SDK is banned
+(`feedback_cf_api_total_eradication`) and `cloudflared` CLI has no
+Access-application create subcommand — so the operator must author it
+in the dashboard before off-LAN clients can reach the Pi.
+
+1. Click **Zero Trust** in the sidebar.
+2. Click **Access** → **Applications**.
+3. Click **Add an application**, then **Self-hosted**.
+4. Set **Application name** to the hostname (e.g. `ssh.maxy.bot`).
+5. Set **Application domain** to the same hostname. **Subdomain** is the
+   first DNS label (`ssh`), **Domain** is the registered parent zone
+   (`maxy.bot`), **Path** stays blank.
+6. Click **Next** through the identity/CORS pages (defaults are fine
+   for a single-operator setup).
+7. On the **Add policies** page, click **Add a policy**.
+8. **Policy name:** "Operator allow". **Action:** `Allow`.
+9. Under **Configure rules** → **Include**, add a rule:
+   **Selector** = `Emails`, **Value** = the operator's email (the same
+   one named in the `ACTION REQUIRED` block).
+10. Click **Save** to land the policy, then **Add application** to land
+    the application.
+
+Repeat for the SMB hostname if the script printed both. Identity list
+gates both routes; the same emails apply.
+
+**Verify:** From an off-LAN machine run
+`cloudflared access login https://ssh.<brand>.<rootdomain>`. Cloudflare
+prompts for the operator email, sends a one-time PIN, and returns to a
+success page. Then `cloudflared access ssh --hostname ssh.<brand>.<rootdomain>`
+opens an SSH prompt to the Pi.
+
+---
+
 ## Where tunnels live in the dashboard (as of 2026-04)
 
 Tunnels are under **Zero Trust** → **Networks** → **Tunnels**. This is not in the top-level sidebar — it is under the Zero Trust sub-dashboard, which itself appears in the main sidebar. Cloudflare has moved this location in the past. If **Networks** → **Tunnels** is not visible under Zero Trust, the label has likely been renamed; look for "Tunnels" under Networks or Access.