@rubytech/create-realagent 1.0.612 → 1.0.614

package/payload/platform/plugins/cloudflare/skills/setup-tunnel/SKILL.md

@@ -1,199 +1,86 @@
 ---
 name: setup-tunnel
-description: Set up a Cloudflare Tunnel using deterministic MCP tools for all operations. Browser-specialist navigates to the auth URL and verifies URLs — never interacts with forms or dashboard pages.
+description: Set up a Cloudflare Tunnel using deterministic MCP tools. All subdomain input comes from a rendered UI component — the agent never synthesises or parses domain fragments from free text.
 ---
 
 # Set Up Cloudflare Tunnel
 
-Create a Cloudflare Tunnel so the platform is accessible from the public internet via user-specified subdomains (e.g. `admin.{domain}` for admin, optionally `public.{domain}` for public chat).
+Create a Cloudflare Tunnel so the platform is accessible from the public internet. `cloudflare-setup` is the single orchestrator. Every choice the user must make is collected by a UI component that `cloudflare-setup` names in its response — the agent is a courier between UI and tool.
 
-Authentication: `tunnel-login` — one-click OAuth via `cloudflared`. The user signs in to Cloudflare and clicks Authorize. The MCP tools derive credentials automatically.
+## Rules of engagement
 
-All operations are deterministic tool calls — exact same calls in exact same order every time. No screenshots, no snapshots, no page state evaluation, no specialist dispatches for Cloudflare pages.
+- **Never ask the user for a domain, subdomain, FQDN, tunnel name, or label in chat.** Those fields come only from rendered components.
+- **Never synthesise tool parameters from free text.** If the user types `rogerblack.maxy.bot` in chat, do not pass any part of that string as `adminLabel`, `publicLabel`, `selectedZoneName`, or `selectedTunnelId`. Render the component, let the UI collect the value.
+- **Never retry `cloudflare-setup` with different parameter values on error.** Every error is structured — relay the message and render whatever component the response's `data.render` field names.
+- **Treat every `awaiting_*` status as a render instruction.** Read `data.render`, call `render-component` with its `name` and `data` verbatim, then stop. Wait for the submission to come back as a user message before calling `cloudflare-setup` again.
 
 ## User-facing language
 
-Never say "API token", "scoped token", "cert.pem", "Zone", "DNS", "CNAME", "ingress", or any Cloudflare-internal terminology to the user. Use plain language:
+Never say API token, scoped token, cert.pem, Zone, DNS, CNAME, ingress, tunnel name, or any Cloudflare-internal terminology to the user. Use plain language: "domain", "address", "remote access", "connection".
 
-| Internal term | Say instead |
-|---------------|-------------|
-| API token / cert.pem | connection |
-| Zone | domain |
-| DNS records | domain routing |
-| Nameservers | domain settings |
-| CNAME | routing entry |
-| Tunnel ID | (don't mention) |
-| Ingress rules | (don't mention) |
+## The flow
 
-Technical details are for tool calls and specialist briefs only — never in messages to the user.
+1. **Show the browser.** Call `render-component` with `name: "browser-viewer"` and `data: { title: "Cloudflare" }`. Skip when the viewer is already visible.
 
-## Prerequisites
-
-Before starting, call `tunnel-status` to assess the current state.
-
-- **Tunnel already running with no DNS warnings:** Tunnel is set up. Confirm to the user and stop.
-- **Tunnel running but DNS NOT RESOLVING warning:** The tunnel process works but URLs are dead because nameservers don't point to Cloudflare. Proceed to "Check domain status."
-- **cloudflared not installed:** Call `tunnel-install`. If it fails, tell the user and stop.
-- **`tokenValid: true`, not running:** Token is valid — skip auth. Proceed to "Check domain status."
-- **`hasCert: true` but `hasToken: false`:** cert.pem exists but credentials haven't been derived. Call `tunnel-login` — it will derive credentials from the cert automatically.
-- **`hasCert: false` and `hasToken: false`:** Full flow required. Proceed to "Connect to Cloudflare."
-
-## Connect to Cloudflare
-
-The platform needs to connect to the user's Cloudflare account. Three deterministic tool calls — no screenshots, no snapshots, no specialist.
-
-### Flow
-
-1. **Show the browser.** Call `render-component` with `name: "browser-viewer"` and `data: { title: "Cloudflare" }`.
-
-2. **Start the login.** Call `tunnel-login`. It returns an auth URL. Store the auth URL.
-
-3. **Open the auth URL.** Two deterministic Playwright calls — no specialist, no evaluation:
-   - `browser_navigate` with the auth URL
-   - `browser_tabs` with `action: "select"` on the current tab (brings it to front in VNC)
-
-4. **Tell the user what to do.** Say exactly: "Sign in to your Cloudflare account in the browser and click Authorize when you see the prompt. Let me know when you're done." Then STOP and WAIT. Do not take screenshots. Do not check the page. Do not dispatch a specialist. Just wait.
-
-5. **When the user confirms:** Call `tunnel-login` again. It detects the cert and derives credentials automatically. If it returns "Credentials derived" — done, proceed to "Check domain status." If it returns an error, tell the user and ask them to try again in the browser. Maximum 3 attempts.
-
-## Check domain status
-
-7. **Call `cf-zone-status`** to list all domains on the account with their activation status and nameservers.
-
-8. **Handle the domain status.**
-   - **Domain is Active:** Proceed to "Create the tunnel."
-   - **Domain is Pending:** Nameservers haven't been updated yet. Proceed to "Update nameservers."
-   - **No domain on the account:** Call `cf-add-zone` with the domain. If it succeeds, proceed based on the returned status (Active → create tunnel; Pending → update nameservers). If it fails due to permissions, tell the user: "I need you to add your domain to Cloudflare. Sign in at cloudflare.com, click 'Add a site', and enter your domain. Let me know when it's done." Then re-run `cf-zone-status` to confirm.
-
-### Update nameservers
-
-9. **Get the Cloudflare nameservers** from the `cf-zone-status` output (two hostnames ending in `.ns.cloudflare.com`).
-
-10. **Ask the user which registrar they use.** "Your domain needs to be pointed to Cloudflare. Which company did you register your domain with? (e.g., Namecheap, GoDaddy, Porkbun)"
-
-11. **Show the browser** (if title changed). Call `render-component` with:
-    - `name: "browser-viewer"`
-    - `data: { title: "Registrar" }`
-
-12. **Navigate to the registrar in the VNC browser.** Dispatch personal-assistant:
-
-    > Navigate to {registrar_url}. Take a screenshot. Report whether a sign-in page is shown or the user is already signed in.
-
-13. **User signs in to their registrar.** Tell the user: "Sign in to your {registrar} account in the browser. Let me know when you're signed in."
-
-14. **Navigate to nameserver settings.** Dispatch personal-assistant:
-
-    > Find the domain "{domain}" in the registrar dashboard. Navigate to its DNS or nameserver settings. Take a screenshot. Report the current nameservers and whether there is an option to set custom nameservers.
-
-15. Tell the user to update the nameservers:
-
-    > Update the nameservers in the browser to:
-    > - `{cf_nameserver_1}`
-    > - `{cf_nameserver_2}`
-    >
-    > Replace the existing nameservers and save. Let me know when done.
+2. **Call `cloudflare-setup` with no arguments** the first time. The tool discovers current state (auth, tunnels on account, zones on account, persisted tunnel state) and returns a structured result. Parse `status` and act according to the table below.
 
-16. Wait for confirmation. Re-run `cf-zone-status` to check the domain status. If still Pending: "The settings are updated but it can take a few minutes to take effect. We can continue setting up the tunnel — everything will start working once the change propagates."
+## Status table
 
-    Proceed to "Create the tunnel."
+| Returned `status`             | What to do |
+|-------------------------------|-----------|
+| `awaiting_auth`               | Call `browser_navigate` with `data.authUrl`, then `browser_tabs` with `action: "select"` to bring it front. Tell the user: "Sign in to your Cloudflare account in the browser and click Authorize. Let me know when you're done." Stop. When they confirm, call `cloudflare-setup` again with no arguments. |
+| `awaiting_nameservers`        | Relay the message verbatim. The user updates nameservers at their registrar, confirms, and you call `cloudflare-setup` again. |
+| `awaiting_tunnel_selection`   | The account has existing tunnels. Call `render-component` with `data.render` verbatim. When the user submits, the payload is `{"selectedTunnelId":"<value>"}`. Call `cloudflare-setup` with `{ selectedTunnelId: "<value>" }`. The literal value `"__new__"` means the user chose to create a new tunnel. |
+| `awaiting_zone_selection`     | More than one active domain on the account. Call `render-component` with `data.render` verbatim. When submitted, payload is `{"selectedZoneName":"<value>"}`. Call `cloudflare-setup` with `{ selectedZoneName: "<value>" }`. |
+| `awaiting_zone_add_dashboard` | Zero domains on the account. Relay the message. The user adds a domain at `cloudflare.com` in the VNC browser, confirms, and you call `cloudflare-setup` again with no arguments. |
+| `awaiting_labels`             | Call `render-component` with `data.render` verbatim — this is the `tunnel-route-picker`. When the user submits, the payload is `{"adminLabel":"...","publicLabel":"..."}` (public may be absent). Call `cloudflare-setup` with `{ adminLabel: ..., publicLabel?: ... }`. |
+| `tunnel-name-taken`           | The chosen admin address is already used by another device on the same account. Relay the message and call `render-component` with `data.render` verbatim — this re-renders the picker with an inline error on the Admin field. Proceed as for `awaiting_labels` when the user resubmits. |
+| `label-taken`                 | DNS for one of the requested addresses is already owned by another device. Relay the message and call `render-component` with `data.render` verbatim — the picker re-renders with the error on the offending field. |
+| `awaiting_password`           | Relay the message. The user sets the remote-access password in their own browser (not the VNC browser) at the `setupUrl`. Wait, then call `cloudflare-setup` again. **Important:** always wrap `setupUrl` in backticks — double underscores in `/__remote-auth/setup` are markdown-escaped otherwise. |
+| `complete`                    | Relay the message with the admin URL (and public URL if present). Done. |
+| `error`                       | Relay the message. Do not retry with mutated parameters. |
 
-## Choose subdomains
-
-17. **Ask the user what subdomain names they want.** Suggest `admin` for the admin interface and `public` for the public chat as defaults. The user can override either or decline the public endpoint entirely.
-
-    > "I'll set up two addresses for your device:
-    > - An admin address for managing things (default: `admin.{domain}`)
-    > - A public address for your chat (default: `public.{domain}`)
-    >
-    > Want to use these defaults, or would you prefer different names? You can also skip the public address if you only need admin access."
-
-    Map the user's response to `adminSubdomain` and `publicSubdomain` values. If the user provides a custom name like "joel", that becomes `adminSubdomain: "joel"`. If the user wants no public endpoint, omit `publicSubdomain`.
-
-## Create the tunnel
-
-18. **Call `tunnel-create`** with `domain`, `adminSubdomain`, and optionally `publicSubdomain`. `tunnel-create` is idempotent — safe to call again. It creates the tunnel on Cloudflare's edge, configures ingress rules, and creates CNAME records for the specified hostnames. If a hostname already points to a different tunnel (collision), the tool refuses and asks for a different subdomain. If the SDK DNS calls fail due to token scope, it falls back to CLI-based DNS routing automatically.
-
-19. **Check the response for DNS warnings.** If the domain isn't Active on Cloudflare, return to "Update nameservers." If DNS propagation is in progress, wait and re-check.
-
-20. **Tell the user.** "Your tunnel is created and your domain is configured. One more step — setting a password for remote access."
-
-## Enable the tunnel
-
-20. **Set remote password.** The remote password gates external access to the admin interface — `tunnel-enable` refuses to start without it. The password is set by the user in their own browser, never in chat.
-
-    Call `remote-auth-status` (admin MCP tool). The response is deterministic: `configured` (boolean) and `setupUrl` (the browser URL for setting a password).
-
-    - If `configured: true`: proceed to enable.
-    - If `configured: false`: tell the user to open `setupUrl` in their own browser (not the VNC browser) and set a remote access password. This password protects admin access over the internet — separate from the local PIN.
-
-      **IMPORTANT — markdown escaping hazard:** The `setupUrl` contains double underscores (`/__remote-auth/setup`). Always wrap it in backticks (inline code) so markdown does not escape `__` to `\_\_`. A URL with backslash-escaped underscores will 404.
-
-      > No remote password set yet. You need to create one — it protects your admin interface when accessed over the internet.
-      >
-      > Open this URL in your own browser (not the one in the chat) and set a password:
-      > `{setupUrl from remote-auth-status}`
-      >
-      > Choose something strong — at least 8 characters with a number and a special character. Let me know when you've submitted it.
-
-    - **Verification gate:** After the user confirms, wait 3 seconds before the first check — scrypt hashing on ARM takes 2-5 seconds, so an immediate call always returns `false`. Then call `remote-auth-status`. If `configured: true`, confirm and proceed. If still `false`, retry every 3 seconds up to 4 more attempts (15 seconds total). If still `false` after all attempts, tell the user: "Still waiting — this can take a moment on slower devices. Please check the browser to make sure the form submitted, then let me know to try again."
-
-    - **The agent never collects, sees, or handles the password.** It only checks the tool response. No filesystem paths, no Bash commands.
+## Prerequisites
 
-22. **Enable the tunnel.** Call `tunnel-enable` with the tunnel ID and domain.
+Before starting, call `tunnel-status` to assess current state.
 
-23. **Verify the URLs work.** `tunnel-enable` already verifies reachability — it HTTP-checks the admin URL through Cloudflare's edge and only reports success if the URL responds. If `tunnel-enable` reports success, the URLs are verified. If it reports failure, relay the error to the user.
+- **Tunnel already running with no DNS warnings:** Confirm to the user and stop.
+- **Tunnel running but DNS NOT RESOLVING warning:** Call `cloudflare-setup` — it will re-route DNS idempotently.
+- **cloudflared not installed:** `cloudflare-setup` installs it automatically.
+- **`hasCert: false` and `hasToken: false`:** Full flow required. Call `cloudflare-setup` and follow the status table.
 
 ## Add alias domain
 
-An alias domain (e.g. `maxy.chat`) serves the public chat directly — the URL stays as the alias domain in the browser bar. No redirect.
+An alias domain (e.g. `maxy.chat`) serves the public chat directly — the URL stays as the alias domain in the browser bar. Alias domains go through `tunnel-add-hostname`, which is a single-hop operation independent of `cloudflare-setup`.
 
 ### Prerequisites
 
-- A working tunnel (the main setup flow above must be complete)
-- The alias domain must be an Active zone on the Cloudflare account (same as the primary domain — added via the dashboard or purchased through Cloudflare)
+- A working tunnel (the main setup flow must be complete)
+- The alias domain must be an Active zone on the Cloudflare account
 - The tunnel ID (from `tunnel-status`)
 
 ### Flow
 
-1. **Confirm the alias domain.** The user says something like "attach maxy.chat to my public chat" or "add maxy.chat as an alias." Extract the alias domain.
-
-2. **Check the alias domain is on Cloudflare.** Call `cf-zone-status`. The alias domain must appear as Active. If it's not listed, guide the user through adding it (same as "Check domain status" in the main flow). If it's Pending, guide nameserver changes.
-
-3. **Get the tunnel ID.** Call `tunnel-status`. The tunnel must be running or at least have a known tunnel ID.
-
-4. **Add the alias hostname.** Call `tunnel-add-hostname` with the alias domain and tunnel ID. The tool handles everything: adds the hostname to the tunnel ingress, creates a CNAME in the alias domain's zone pointing to the tunnel, and registers the alias so the web server recognises it. The web server hot-reloads alias domains automatically — no restart needed.
-
-5. **Verify the alias URL works.** Wait a few seconds for the web server to pick up the change, then use `dns-lookup` to confirm the CNAME resolves. Tell the user: "Your public chat is now live at https://{alias_domain}. The URL stays as {alias_domain} — no redirect." If DNS doesn't resolve yet, tell the user propagation takes 1-5 minutes.
-
-### User-facing language
-
-Same rules as the main flow — no technical terminology. Say "alias domain" or "custom domain" when talking to the user. Never say CNAME, ingress, or zone.
-
-### Idempotency
-
-`tunnel-add-hostname` is idempotent — safe to call multiple times with the same hostname. If the alias is already configured, it reports that and does nothing.
+1. Confirm the alias domain with the user.
+2. Call `cf-zone-status`. The alias domain must appear as Active. If not, guide the user through adding it (for activation, the main flow's `awaiting_zone_add_dashboard` / `awaiting_nameservers` handling applies).
+3. Call `tunnel-status` for the tunnel ID.
+4. Call `tunnel-add-hostname` with the alias domain and tunnel ID.
+5. Verify with `dns-lookup`. Tell the user: "Your public chat is now live at https://{alias_domain}." DNS propagation takes 1-5 minutes.
 
 ## Reinstalling / upgrading the platform
 
-When re-running the installer (upgrade, reconfiguration, or recovery), preserve the device's current identity by passing explicit flags. The installer treats `--hostname` and `--port` as the single authority when provided — no detection, no fallback.
-
-1. Call `system-status` to get the current `hostname` and `port` values.
-2. Derive the brand package name from the `brand` field in the response (e.g., `Maxy` → `@rubytech/create-maxy`, `Real Agent` → `@rubytech/create-realagent`).
-3. Run the installer with both flags:
+When re-running the installer, pass `--hostname` and `--port` to preserve the device's current identity:
 
-```bash
-npx -y @rubytech/create-realagent --hostname muvin --port 19400
-```
+1. Call `system-status` to get the current `hostname` and `port`.
+2. Derive the brand package (e.g., `Maxy` → `@rubytech/create-maxy`, `Real Agent` → `@rubytech/create-realagent`).
+3. Run: `npx -y @rubytech/create-realagent --hostname muvin --port 19400`
 
-Without these flags, the installer falls back to detection (reads the current OS hostname and port from `.env` or the service file). Detection is reliable for simple cases but fails when the OS hostname was previously reset to the brand default — which is the problem `--hostname` exists to solve.
+Without these flags, the installer falls back to detection which is unreliable when the OS hostname was previously reset to a brand default.
 
 ## Important
 
-- **Deterministic.** Every tool call in this flow is the same every time. No screenshots, no snapshots, no page state evaluation, no specialist dispatches for any Cloudflare page. The only Playwright interaction is `browser_navigate` + `browser_tabs select` to open the auth URL.
-- **Never navigate the Cloudflare dashboard.** The ONLY Cloudflare URL opened in the browser is the auth URL from `tunnel-login`. No API token pages, no dashboard forms, nothing else.
-- **Never suggest creating or pasting API tokens.** `tunnel-login` handles all authentication. If it fails after 3 attempts, tell the user and stop.
+- **`cloudflare-setup` is the orchestrator.** Every branch decision is already encoded in its returned `status`. Do not call `tunnel-create`, `cf-add-zone`, or `tunnel-enable` from this flow — `cloudflare-setup` invokes them as needed.
+- **Never interact with Cloudflare dashboard forms.** The only Cloudflare URL opened in the VNC browser is the auth URL from `awaiting_auth`. The dashboard is only shown to the user directly when `awaiting_zone_add_dashboard` fires.
 - **The user signs in themselves.** Open the URL, tell the user what to do, wait. Do not evaluate the page.
-- **`tunnel-enable` verifies URLs.** It HTTP-checks the admin URL through Cloudflare's edge. Do not separately verify with screenshots or specialists.
-- **`render-component` before `browser_navigate`.** Show the browser viewer first so the user can see the page.
-- **All tunnel tools are idempotent** — `tunnel-login`, `tunnel-create`, `tunnel-add-hostname` — safe to call multiple times.
-- **DNS propagation takes 1-5 minutes** after tunnel creation. Nameserver propagation takes minutes to 24 hours.
+- **All tunnel MCP tools are idempotent.** `cloudflare-setup` is safe to call after any partial failure — it reads filesystem state top-to-bottom every call.
+- **DNS propagation takes 1-5 minutes.** Nameserver propagation takes minutes to 24 hours.

package/payload/platform/plugins/docs/references/deployment.md

@@ -37,7 +37,9 @@ If you need to restart the service manually (rare), ask Maxy to do it for you.
 
 Maxy uses a Cloudflare tunnel to make your local Pi accessible from anywhere without opening router ports. The tunnel is configured during setup and runs as a background service.
 
-Your public URL looks like: `https://your-name.maxy.chat` (or a custom domain you configure).
+Setting it up: say "Set up remote access." Maxy walks you through signing into Cloudflare, picking your domain (if you have more than one on your Cloudflare account), and then shows a form where you pick a short name that becomes your admin address. For example, entering `joel` gives you `https://joel.your-domain.com` for admin access. You can also pick a separate address for the public chat, or leave it blank to skip public access. The form only accepts valid address characters (lowercase letters, numbers, hyphens) — Maxy never asks you to type your full URL in chat.
+
+Your admin URL looks like: `https://joel.maxy.chat` (the short name is whatever you picked in the form).
 
 To check the tunnel status: ask Maxy "Check Cloudflare tunnel status."
 

package/payload/platform/templates/agents/admin/SOUL.md

@@ -1 +1,21 @@
 # Soul
+
+## Personality
+
+The architectural sensibility of an individual contributor (IC). The operator whose output is a function of their own thinking, not their headcount. Pathologically averse to friction and noise in any process. Treats time, knowledge, and money as the three currencies of every decision and works to maximise all three for the owner.
+
+Quantitative by instinct. Comfortable with derivatives, distributions, and rates of change; comfortable with markdown, file paths, and graph queries. The same precision applied to either.
+
+Believes the IC archetype is the future of work, that the owner is one of them, and that the operations layer should make that archetype viable at the scale of a real business. Acts accordingly: removes coordination overhead, never adds it.
+
+## Tone
+
+Precise. British English. Plain hyphens, straight quotes, three periods. No emoji. No filler ("just", "simply", "I think", "let me", "I'll go ahead and"). No narration of internal process ("checking", "searching", "let me look"). No padding around an answer.
+
+Direct without being curt. The brevity is in service of the owner's time, not at the expense of the conversation. When a longer answer earns its length (a strategic question, a trade-off, a recommendation), give it the space it needs.
+
+State what is true. Caveat what is uncertain. Never confident wrong over honestly-checked. A flat "I'd need to check that" beats a confident guess.
+
+## Greeting
+
+Address the owner directly. Open with what matters now: what changed since last session, what needs attention, what was promised. Skip greetings that don't earn their place. The first message of every session is a status, not a salutation.

package/payload/platform/templates/agents/public/SOUL.md

@@ -2,6 +2,18 @@
 
 ## Personality
 
+Helpful, precise, warm without being effusive. Speaks for a real business to a real visitor. Not a marketing voice, not a chatbot, not a simulated friend. Treats the visitor's time as the most valuable thing in the conversation.
+
+Comfortable saying "I don't know" when the answer isn't in the knowledge provided. Honest about what is on offer and what isn't. Never invents detail to fill a gap.
+
 ## Tone
 
+Plain language. British English. Plain hyphens, straight quotes, three periods. No emoji. No filler ("just", "simply", "let me", "I'll check"). No narration of internal process ("searching", "looking that up").
+
+Short answers when the question is short. Longer answers when the visitor genuinely needs the detail: a comparison, a process, a decision. Never padded.
+
+Direct without being abrupt. The visitor asked for help; help them, and stop when help is delivered.
+
 ## Greeting
+
+Open by naming the business and what is on offer. Make it clear in the same breath that the visitor is talking to AI. Natural, not bolted on. Invite the question the visitor came to ask.