npm - @rubytech/create-maxy-code - Versions diffs - 0.1.0 - Mend

@rubytech/create-maxy-code 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (1821) hide show

package/payload/platform/plugins/business-assistant/references/invoicing.md ADDED Viewed

@@ -0,0 +1,163 @@
+# Invoicing & Payment
+## Invoice Creation Workflow
+1. **Gather data:**
+   - Customer name, address (from contact record or conversation)
+   - Line items with descriptions and amounts
+   - Payment terms (from memory, default "on receipt")
+   - Invoice number: `INV-{YYYYMMDD}-{SLUG}` (SLUG = customer name, uppercased, max 20 chars)
+2. **Look up business details from memory:**
+   - Company name, address, phone, email
+   - Bank details (sort code, account number, account name)
+3. **Write HTML invoice** to the customer-facing document folder:
+   ```
+   memory/users/{phone}/documents/invoices/INV-{YYYYMMDD}-{SLUG}.html
+   ```
+   Use the template below. The HTML must be self-contained — all styles inline, no external resources.
+4. **Convert to PDF:**
+   Call `document_to_pdf` with the memory path. The PDF is saved alongside the HTML with a `.pdf` extension.
+5. **Present the PDF to the business owner immediately.**
+   Do not just announce the file exists — deliver it. Send the PDF via WhatsApp (self-chat) so the business owner can review it on their phone. Include a summary:
+   > "Here's the invoice for [customer] — [amount]. I've saved it at [path]. Want me to send it to [customer] on WhatsApp?"
+   If the current channel is webchat (not WhatsApp/iMessage), the `message` tool cannot attach files to the chat session. In that case, state the PDF path clearly and offer to send it via WhatsApp instead.
+6. **On approval, send to customer:**
+   Use `message` tool with channel `"whatsapp"` and the PDF path as attachment. Always include a caption:
+   > "Hi [customer], here's the invoice for [work description]. Payment details are on the invoice. Any questions, just let me know!"
+7. **Update records:**
+   - Update contact record status to `invoiced` via `contact_update`
+   - Note the invoice number and amount in memory
+## HTML Invoice Template
+Use this structure for all invoices. Adjust company details, colours, and content to match the business. All CSS must be inline in a `<style>` block — no external stylesheets.
+```html
+<!DOCTYPE html>
+<html>
+<head>
+<meta charset="UTF-8">
+<style>
+  body { font-family: 'Helvetica Neue', Arial, sans-serif; margin: 0; padding: 40px; color: #333; }
+  .invoice-header { display: flex; justify-content: space-between; align-items: flex-start; margin-bottom: 40px; border-bottom: 3px solid #2c3e50; padding-bottom: 20px; }
+  .company-name { font-size: 28px; font-weight: 700; color: #2c3e50; }
+  .company-details { font-size: 12px; color: #666; line-height: 1.6; margin-top: 5px; }
+  .invoice-title { font-size: 36px; font-weight: 300; color: #2c3e50; text-align: right; }
+  .invoice-meta { text-align: right; font-size: 13px; color: #666; margin-top: 8px; line-height: 1.8; }
+  .invoice-meta strong { color: #333; }
+  .addresses { display: flex; justify-content: space-between; margin-bottom: 40px; }
+  .address-block { width: 45%; }
+  .address-label { font-size: 11px; text-transform: uppercase; letter-spacing: 1px; color: #999; margin-bottom: 8px; font-weight: 600; }
+  .address-content { font-size: 13px; line-height: 1.7; }
+  table { width: 100%; border-collapse: collapse; margin-bottom: 30px; }
+  thead th { background: #2c3e50; color: white; padding: 12px 15px; text-align: left; font-size: 12px; text-transform: uppercase; letter-spacing: 0.5px; }
+  thead th:last-child { text-align: right; }
+  tbody td { padding: 15px; border-bottom: 1px solid #eee; font-size: 13px; }
+  tbody td:last-child { text-align: right; font-weight: 500; }
+  .item-desc { font-size: 11px; color: #888; margin-top: 4px; }
+  .total-row td { border-top: 2px solid #2c3e50; font-size: 16px; font-weight: 700; color: #2c3e50; padding-top: 15px; }
+  .payment-section { background: #f8f9fa; padding: 25px; border-radius: 6px; margin-top: 20px; }
+  .payment-title { font-size: 13px; font-weight: 700; text-transform: uppercase; letter-spacing: 0.5px; color: #2c3e50; margin-bottom: 12px; }
+  .payment-details { font-size: 13px; line-height: 1.8; }
+  .footer { margin-top: 40px; text-align: center; font-size: 11px; color: #999; border-top: 1px solid #eee; padding-top: 15px; }
+  /* Print / PDF styles */
+  @media print {
+    body {
+      font-size: 12pt;
+      line-height: 1.4;
+      color: black;
+      background: white !important;
+      padding: 0;
+    }
+    @page {
+      size: A4;
+      margin: 1in;
+    }
+    .payment-section { page-break-inside: avoid; }
+    table { page-break-inside: avoid; }
+  }
+</style>
+</head>
+<body>
+<div class="invoice-header">
+  <div>
+    <div class="company-name">[COMPANY NAME]</div>
+    <div class="company-details">
+      [Address line 1]<br>[Address line 2]<br>[City, Postcode]<br>[Phone]<br>[Email]
+    </div>
+  </div>
+  <div>
+    <div class="invoice-title">INVOICE</div>
+    <div class="invoice-meta">
+      <strong>Invoice No:</strong> [INV-YYYYMMDD-SLUG]<br>
+      <strong>Date:</strong> [DD Month YYYY]<br>
+      <strong>Due:</strong> [Payment terms]
+    </div>
+  </div>
+</div>
+<div class="addresses">
+  <div class="address-block">
+    <div class="address-label">Bill To</div>
+    <div class="address-content">
+      <strong>[Customer Name / Company]</strong><br>
+      [Attn: Contact Name (if different)]<br>
+      [Address]<br>[City, Postcode]
+    </div>
+  </div>
+</div>
+<table>
+  <thead>
+    <tr><th>Description</th><th>Amount</th></tr>
+  </thead>
+  <tbody>
+    <!-- Repeat for each line item -->
+    <tr>
+      <td>[Item description]<div class="item-desc">[Optional detail]</div></td>
+      <td>[Currency symbol][Amount]</td>
+    </tr>
+    <tr class="total-row">
+      <td><strong>Total</strong></td>
+      <td><strong>[Currency symbol][Total]</strong></td>
+    </tr>
+  </tbody>
+</table>
+<div class="payment-section">
+  <div class="payment-title">Payment Details</div>
+  <div class="payment-details">
+    <strong>Account Name:</strong> [Account name]<br>
+    <strong>Sort Code:</strong> [XX-XX-XX]<br>
+    <strong>Account Number:</strong> [XXXXXXXX]<br>
+    <strong>Reference:</strong> [Invoice number]
+  </div>
+</div>
+<div class="footer">
+  [Payment terms message, e.g. "Payment is due on receipt. Thank you for your business."]
+</div>
+</body>
+</html>
+```
+Fill in all `[placeholders]` from memory and conversation context. Do not leave any placeholders in the final HTML.
+## Payment Chase Protocol
+1. After a job is completed, prompt business owner: "Job done at [customer]? Shall I send the invoice?"
+2. Check memory for configured chase timings (`invoice_reminder_days`, default 7; `invoice_escalate_days`, default 14)
+3. If invoice unpaid after first reminder period:
+   > "Hi [customer], just a gentle reminder about the invoice for [work] on [date]. The amount was [amount]. Let me know if you have any questions!"
+4. If still unpaid after escalation period, notify business owner:
+   > "[Customer] hasn't paid the [amount] invoice from [date]. Want me to send another reminder or shall I leave it?"
+5. Never be aggressive. Never threaten. Always friendly and professional.
+6. Track payment status in memory and update contact record via `contact_update`.

package/payload/platform/plugins/business-assistant/references/profiling.md ADDED Viewed

@@ -0,0 +1,50 @@
+# Owner Profiling
+You accumulate structured knowledge about the business owner through observation and conversation. This knowledge lives as Preference nodes in the graph, linked to the UserProfile with evidence trails.
+## When to observe
+Write a preference when:
+- The owner explicitly states one ("I prefer…", "Don't do…", "Always…")
+- The owner corrects your output in a way that implies a preference (shortening a verbose draft, changing tone, rejecting a suggestion pattern)
+- The owner's behaviour consistently demonstrates a pattern across multiple turns (always responds quickly to scheduling questions, ignores low-priority notifications)
+Do not write a preference from a single ambiguous interaction. Wait for reinforcement or ask a clarifying question when it won't disrupt the flow.
+## How to write
+Call `profile-update` with:
+- `category`: communication | scheduling | decision | workflow | content | interaction
+- `key`: a specific identifier (e.g. `response_length`, `meeting_time`, `approval_style`)
+- `value`: the preference in natural language (e.g. "terse — prefers 1-3 sentence responses")
+- `source`: `explicit` (they said it) or `behavioural` (you observed it)
+- `mode`: `reinforce` (re-observed), `update` (value changed), `contradict` (value contradicts prior)
+- `conversationId`: the current conversation ID for evidence linking
+When the owner shares personal details (timezone, role, expertise), include `profileFields` to update the UserProfile directly.
+## Boundaries — what to never store
+- Financial credentials, passwords, API keys, account numbers
+- Health information not voluntarily shared in a business context
+- Relationship or family details not voluntarily shared
+- Political or religious views
+- Anything the owner says "don't remember that" about — honour immediately via `profile-delete`
+## Behaviour
+- Observe quietly. Do not announce "I'm updating your profile" or "I noticed you prefer X". The profile is a background process, not a foreground feature.
+- If uncertain about an observation, ask a clarifying question — but only when it won't disrupt the conversation flow. "Do you generally prefer shorter responses, or was that specific to this task?" is appropriate. "I'm building your profile — do you prefer X?" is not.
+- When the owner asks "what do you know about me?", call `profile-read` and present the summary conversationally — not raw data.
+- When the owner says "forget that" or "don't remember X", call `profile-delete` with the matching category and key. Confirm the deletion.
+## Categories guide
+| Category | What to capture | Example keys |
+|---|---|---|
+| communication | How they write, how they want responses | response_length, formality, humour_tolerance, explanation_depth |
+| scheduling | Work hours, meeting preferences | work_hours, meeting_preferences, day_off, response_urgency |
+| decision | How they approve or reject | approval_style, risk_tolerance, data_requirements, delegation_comfort |
+| workflow | How they want tasks handled | task_granularity, update_frequency, autonomy_level |
+| content | Document and content preferences | document_style, naming_conventions, brand_voice_notes |
+| interaction | Patterns with the assistant | greeting_preference, session_start_ritual, feedback_style |

package/payload/platform/plugins/business-assistant/references/quoting.md ADDED Viewed

@@ -0,0 +1,56 @@
+# Quoting
+## Photo-to-Quote (Handwritten)
+1. Business owner sends a photo of their handwritten quote
+2. Read the handwriting using vision
+3. Format into a clean, professional quote:
+   - Customer name and address
+   - Description of work
+   - Labour cost (itemised if multiple tasks)
+   - Parts (if applicable — customers may buy parts directly)
+   - Materials markup (if set in memory)
+   - Total
+   - Validity period (default: 30 days)
+   - Payment terms
+4. Send back to business owner for approval: "Here's the formatted quote. Shall I send it to [customer]?"
+5. On approval → send to customer via WhatsApp
+## Quote from Conversation
+1. Business owner tells you the details verbally (text or voice)
+2. Format as above
+3. Confirm and send
+## Quote Formatting Template
+Quotes sent to customers should be clean, readable, and professional — but delivered as a WhatsApp message (not a PDF, unless the business owner requests one).
+```
+**Quote for [Customer Name]**
+[Business Name] — [Date]
+**Description of work:**
+[Itemised list of work to be done]
+**Cost breakdown:**
+- Labour: £[amount]
+- Parts: £[amount] (if applicable)
+- Materials: £[amount] (if applicable)
+- **Total: £[amount]**
+Valid for 30 days.
+Payment terms: [from memory, default "on completion"]
+Any questions, just reply to this message!
+```
+For formal PDF quotes, use the same workflow as invoicing — write HTML, convert with `document_to_pdf`, send as attachment. See `references/invoicing.md` for the PDF workflow.
+## Quote Follow-Up
+- If no response after configurable days (check memory for `quote_followup_days`, default 3): send a gentle nudge to the customer
+  > "Hi [customer]! Just following up on the quote I sent over for [work description]. Any questions or shall I go ahead and book it in?"
+- If no response after escalation period (check memory for `quote_escalate_days`, default 7): notify business owner and ask if they want to chase or drop it
+- Store outcome in memory: accepted / declined / no response
+- Update contact record status via `contact_update`

package/payload/platform/plugins/business-assistant/references/scheduling.md ADDED Viewed

@@ -0,0 +1,127 @@
+# Scheduling & Briefings
+## Booking Protocol
+When booking an appointment:
+1. Check memory for the business owner's schedule and known commitments
+2. **Check geography** — where is the customer? What postcode area? Where are existing jobs that day?
+3. **Prefer geographic clustering** — offer slots where the business owner is already nearby:
+   - Use your knowledge of geography, towns, and postcodes to judge proximity. **Do NOT rely on postcode prefixes alone** — different prefixes can be adjacent (e.g., CM23 and CB11 are ~15 minutes apart despite different area codes), and same prefixes can span large areas.
+   - Think in terms of **towns and travel time**, not prefix strings.
+   - If a routing tool (OSRM) is available, use it for accurate drive times.
+   - If the customer's area matches an existing job day, offer that day first: "[name]'s already in the Stansted area on Tuesday — would Tuesday afternoon work?"
+4. Offer 2-3 time options (never just one — gives the customer choice)
+5. Allow enough time per job type (load from industry overlay)
+6. Leave travel time between jobs:
+   - Same town / nearby villages: 10-20 minutes
+   - Neighbouring towns: 20-35 minutes
+   - Different areas (30+ miles): 45+ minutes
+   - If a routing tool is available, use actual drive times instead of estimates
+7. **Check for squeeze-in opportunities** — if there's a gap between existing jobs and the new customer is nearby, offer that gap
+8. Confirm with customer
+9. If customer can't make any options → offer alternatives, handle the ping-pong
+10. Only escalate to business owner if: no slots available, customer insists on a taken time, or unusual job type
+**Always store the customer's postcode/area in memory.** Essential for future geographic clustering.
+**Escalation format:** Short, include location context:
+> "New booking request: Mrs Jenkins, 42 Oak Lane, CM23. Boiler not firing — sounds like ignition. She's available Tue/Wed/Thu afternoon. You're already in CM23 on Tuesday (Dave Smith, 9am). Shall I book her in for Tuesday 11am?"
+## Schedule Optimisation
+**You are the business owner's logistics manager, not just a diary.** Minimise driving. Maximise billable time. Think geographically.
+### Rescheduling suggestions (proactive, to business owner)
+When you notice a scheduling inefficiency, suggest a fix:
+> "[name] — Mr Thompson's boiler service is booked for Wednesday in Saffron Walden. But you've got two jobs there on Thursday already. If he's flexible, moving him to Thursday would save you a 40-min round trip. Want me to ask him?"
+Only suggest rescheduling when:
+- The customer is known to be flexible (check memory)
+- The saving is significant (20+ minutes of driving)
+- The job isn't urgent
+- It doesn't push the job more than a few days
+### Emergency reshuffling
+When an emergency comes in, check what can move:
+> "Emergency call — burst pipe in Thaxted, active flooding. Your next job (Mrs Jenkins, 2pm, CM23) is a routine boiler service. She's usually flexible. Want me to reschedule her and slot this in?"
+Always ask the business owner before reshuffling. Never move a job without approval.
+## Morning Briefing
+If a scheduled event is set up for morning briefings, send a daily summary. **Group jobs by area, not just time.** Include postcodes, estimated travel, and total driving time.
+> **Morning [name]! Here's your Tuesday:**
+>
+> **Stansted area:**
+> 9:00am — Mrs Jenkins, 42 Oak Lane, CM23 (boiler service, ~1hr)
+> 10:30am — Dave Smith, 15 Park Road, CM24 (dripping tap, ~30min)
+>
+> **Newport area** (~25 min drive):
+> 12:00pm — Mrs Wilson, 8 High St, CB11 (power flush, ~3hrs)
+>
+> Total: 3 jobs, ~55 min driving. Home by 4pm.
+>
+> **Waiting on:**
+> - Quote sent to Mr Brown (bathroom refit, £4,500) — sent 2 days ago, no reply yet
+> - Invoice unpaid: Mr Thompson, £180, 18 days overdue. Reminder sent Monday
+>
+> **New messages overnight:**
+> - Sarah Collins asked about a leaking radiator. She's in CM23 — I've offered her Wednesday 10am. Waiting for her to confirm.
+## Travel Time Estimation
+- If a routing tool (OSRM) is available, use it for accurate drive times
+- Otherwise, **use your knowledge of geography** — think in terms of actual places, not postcode prefix strings
+- Same town / nearby villages: ~10-15 minutes
+- Neighbouring towns: ~20-35 minutes
+- Cross-area (different towns, 30+ miles): ~45+ minutes
+- Always err on the side of more travel time, not less
+- When in doubt, ask: "How long does it take you to get from [A] to [B]?" and store the answer
+## GPS Integration
+If the business owner's phone is paired as a node, you can query their GPS location on demand using `location.get`:
+- **Customer asks "where is he?"** → Check GPS, give ETA: "[name] left his last job about 15 minutes ago. He should be with you in about 20 minutes."
+- **Late detection** → Query GPS 10 minutes before each appointment. If far away, proactively message the customer about the delay.
+- **End-of-day** → If near home postcode, stop offering same-day appointments.
+- Do NOT track location continuously. Only query when you have a specific reason.
+- Do NOT share exact GPS coordinates with customers. Approximate ETAs and area descriptions only.
+## Geographic Intelligence Over Time
+- Week 1: Only know postcodes from new bookings. Clustering is basic.
+- Month 1: Know 30+ customer locations. Clustering is effective.
+- Month 3: Know typical areas, preferred days per zone, how long jobs actually take. You're a logistics expert.
+- With Kickstart data import: Know 200+ locations from Day 1.
+## Holiday Mode
+When the business owner says they're going away:
+1. Note the dates in memory
+2. Continue responding to customers normally — **DO NOT tell customers the business owner is away** (security risk — empty house)
+3. Instead: "[name]'s fully booked this week but has availability from [return date]. Shall I pencil you in?"
+4. Queue non-urgent matters for when they return
+5. Escalate genuine emergencies (refer to another business owner if one is specified in memory)
+6. Send a summary when they return
+## Onboarding (First Conversation)
+When the business owner first messages, learn their business conversationally:
+1. "What industry is your business in?" → load industry overlay
+2. "What's your standard rate or pricing structure?"
+3. "What area do you cover?"
+4. "What are your working hours?"
+5. "Do you want me to handle incoming WhatsApp messages from customers?"
+6. "Anything else I should know?" (materials markup, specialities, things you don't do)
+7. "Should I give you a morning briefing each day?"
+Store everything in memory. Don't ask all at once — be conversational.

package/payload/platform/plugins/business-assistant/references/task-management.md ADDED Viewed

@@ -0,0 +1,163 @@
+# Task & Session Management
+Every conversation maps to a named, purposeful task. Sessions are not chat logs — they are units of work. This reference governs how you create, track, and complete tasks, and how you name and close sessions.
+---
+## Core Principle
+One session, one task. A session exists to accomplish something specific. If a conversation drifts into a second topic, finish the first, then suggest starting a fresh session for the next piece of work.
+---
+## Task Lifecycle
+```
+pending → active → completed
+                ↘ failed
+                ↘ cancelled
+```
+| status | Meaning |
+|---|---|
+| `pending` | Identified but not yet started |
+| `active` | Work is in progress |
+| `completed` | Done — outcome achieved |
+| `failed` | Abandoned or blocked |
+| `cancelled` | No longer relevant |
+### When to create a task
+Create a task whenever:
+- The user identifies a piece of work to be done ("we need to set up Telegram")
+- You identify work that needs to happen before the user can proceed
+- A multi-step process begins that will span more than one message
+Do not create tasks for simple one-turn exchanges (answering a question, looking up a price).
+### Creating a task
+Use `task-create`. Always pass `sessionKey` (from your system prompt — "Current session key: ...") to link the task to the current conversation automatically:
+```
+task-create {
+  name: "Telegram setup",
+  description: "Configure Telegram bot and webhook for the business",
+  status: "active",
+  priority: "normal",
+  sessionKey: "<value from system prompt>"
+}
+```
+### Updating a task
+Use `task-update` to change name, description, status, priority, due date, or append a progress note:
+```
+task-update {
+  taskId: "<id>",
+  name: "Corrected task name",
+  note: "Renamed to reflect actual scope"
+}
+```
+```
+task-update {
+  taskId: "<id>",
+  status: "completed",
+  note: "Webhook configured and verified"
+}
+```
+Notes are append-only — never overwritten. Name and description changes preserve all note history and relationships.
+### Completing a task
+Use `task-complete` as a shorthand — it sets status to `completed` and appends a closing note:
+```
+task-complete {
+  taskId: "<id>",
+  note: "Telegram bot live, webhook responding"
+}
+```
+---
+## Session Lifecycle
+### Session start
+At the beginning of a session:
+1. Call `session-list` to see recent sessions and open tasks
+2. If there are open or in-progress tasks, surface them: "I can see we started setting up Telegram on Tuesday — want to continue with that, or is there something else?"
+3. If the user's first message makes the session purpose clear, name the session immediately and proceed
+4. If the purpose is not clear from the first message, ask once: "What would you like to work on today?" — then name the session once you have the answer
+5. Never name the session before you know what it's for
+### Naming the session
+Name the Conversation node once the session purpose is clear — this happens after the user's first reply, not on the agent's opening turn:
+```
+session-name {
+  sessionKey: "<value from system prompt>",
+  name: "Telegram setup"
+}
+```
+If the session drifts to a substantially different topic, rename it to reflect what was actually worked on. `session-name` overwrites the previous name.
+### Session end
+When the session is wrapping up:
+1. Summarise what was accomplished
+2. List any pending items or follow-ups
+3. Mark the task complete (or failed/cancelled if blocked)
+4. Close with something like: "That's the Telegram webhook configured. I've marked the task complete."
+---
+## Querying Sessions and Tasks
+### List recent sessions
+```
+session-list {}
+```
+Returns recent conversations with their names, session keys, and any linked tasks. Use this at session start and when the user asks what sessions or work is in progress.
+### List open tasks
+```
+task-list { status: "active" }
+task-list { status: "pending" }
+```
+### Get a specific task
+```
+task-get { taskId: "<id>" }
+```
+---
+## Cross-Session Progress Tracking
+If a user returns to work on a previous task:
+1. Call `session-list` to find the original session and task
+2. Call `task-update` to set `status: "active"` and note the resumption
+3. Pass `sessionKey` in `task-create` for any new tasks in the new session — it links them to the current conversation automatically
+A task can span multiple sessions. Use `task-create` with `sessionKey` each time work resumes in a new conversation.
+---
+## Session-Task Mapping Rules
+- **One active task per session.** Don't split focus.
+- **Multiple sessions per task is fine.** Complex work spans multiple conversations.
+- **Suggest a new session when scope drifts.** "That's a different topic — let me finish the invoice here and we can start a fresh session for the website changes."
+- **Never leave a task in `active` indefinitely.** If work is clearly abandoned, mark it `failed` with a note.
+- **Proactively surface tasks that need attention.** If a task has been active for more than a few days, mention it when the user starts a new session.

package/payload/platform/plugins/cloudflare/PLUGIN.md ADDED Viewed

@@ -0,0 +1,73 @@
+---
+name: cloudflare
+description: Cloudflare Tunnel operations — setup, reset, dashboard guidance. Zero agent-facing MCP tools; every operation is a shell script or a dashboard click-path the operator performs themselves.
+tools: []
+---
+# Cloudflare Tunnel
+Each installation has its own Cloudflare account. The operator signs in with OAuth via `cloudflared tunnel login` (driven by `setup-tunnel.sh`); `cloudflared` writes `cert.pem` to the brand-scoped config directory. The Cloudflare dashboard is the single source of truth for which domains, addresses, and tunnels exist; the plugin never reads or mutates account state via any API path — only `cloudflared` CLI shell-outs the scripts execute, and DNS + HTTPS probes against public surfaces.
+## When to activate
+- Operator mentions Cloudflare, custom domain, public access, or internet access
+- Operator wants to expose the assistant publicly with a custom URL
+- Operator asks about setting up remote access with a custom domain
+- Operator says "set up Cloudflare", "reset the tunnel", "my tunnel is broken", or similar
+## What it unlocks
+- Public internet access via a custom domain
+- Reliable mobile admin access (replacing or supplementing Tailscale)
+- Custom-branded public chat URLs
+- Webhook endpoints on a stable domain
+## Operator-facing surface
+The plugin registers no agent-facing MCP tools. Every Cloudflare operation is driven through one of four sanctioned surfaces — `setup-tunnel.sh`, `reset-tunnel.sh`, `references/manual-setup.md`, or `references/dashboard-guide.md`. See the skill below for the discipline rule that binds the agent to these four.
+### Scripts
+| Script | Purpose |
+|---|---|
+| [`scripts/setup-tunnel.sh`](scripts/setup-tunnel.sh) | Autonomous end-to-end setup: OAuth login, tunnel resolve (operator-supplied identity), DNS route, config + state, service restart, post-restart verification. Invocation: `~/setup-tunnel.sh <brand> <port> <admin-hostname> [<public-hostname>] [<apex-hostname>]`. Required env: `STREAM_LOG_PATH`, `ACCOUNT_DIR`, AND exactly one of `TUNNEL_ID` (operator selected an existing tunnel from `/api/admin/cloudflare/tunnels`) or `TUNNEL_NAME` (operator typed a name to create) per the operator-selected-tunnel fix. The pre-fix derivation `${BRAND}-$(hostname -s)` is removed — the operator's logged-in Cloudflare account is the source of truth for which tunnel exists. Apex hostnames print an `ACTION REQUIRED` block for the dashboard record the CLI cannot create. Step 1 (wrappers faithfully relay third-party CLI) spawns `cloudflared tunnel login`, extracts the argotunnel URL from its stdout, mechanically opens it on the brand's VNC chromium using the install-time-resolved binary (`DISPLAY=${DISPLAY:-${BRAND_VNC_DISPLAY}} "${SETUP_TUNNEL_CHROMIUM_BIN}" <url> &` — `SETUP_TUNNEL_CHROMIUM_BIN` is read from `${MAXY_PLATFORM_ROOT}/config/chromium-binary.path` at script start so Ubuntu Noble laptop's snap-replaced Google Chrome is honoured by the install-time chromium resolver), then polls for `~/.cloudflared/cert.pem` while the operator clicks the zone row + Authorize on the VNC. 180 s budget with a 2-second `step=oauth-login result=awaiting-cert` heartbeat. No CDP auto-click, no DOM matcher. |
+| [`scripts/reset-tunnel.sh`](scripts/reset-tunnel.sh) | Deletes every tunnel on the brand's CF account and wipes `${CFG_DIR}`. Does not touch the platform service, stray CNAMEs, or token-mode connectors — those require dashboard cleanup or `pkill`. Invocation: `~/reset-tunnel.sh <brand>`. No polling blocks — every long-wait is bounded by `cloudflared`'s network round-trip, so no heartbeat contract applies. |
+### Skills
+| Skill | Purpose |
+|---|---|
+| [setup-tunnel/SKILL.md](skills/setup-tunnel/SKILL.md) | Names the four sanctioned surfaces (autonomous / manual / reset / dashboard), the inputs to collect before invoking `setup-tunnel.sh`, and the tool-discipline rule that binds the agent. |
+### References
+| Reference | Topics |
+|---|---|
+| [manual-setup.md](references/manual-setup.md) | Step-by-step human runbook — Steps 0–7 with isolated command blocks. Used when diagnosing a failing scripted step or working on a device where the scripts are not yet deployed. |
+| [dashboard-guide.md](references/dashboard-guide.md) | Click-paths for the operations only the Cloudflare dashboard can perform — sign in, switch accounts, add a site, edit an apex CNAME, verify nameservers, delete a tunnel, manage CNAME records. |
+| [reset-guide.md](references/reset-guide.md) | Decision tree for reset vs. patch, the exact `pkill` incantation for token-mode connectors, and the dashboard cleanup paths for stray records and rogue entries. |
+The agent loads these references on demand via `plugin-read` as the conversation requires. They are not auto-injected into the system prompt.
+### UI contract
+VNC surfacing is post-navigation, never on form submit. Two sites call `useDeviceUrlActions().onShowVnc()` and both fire only after a successful CDP nav: `DeviceUrlBlock` (tool-output URL clicks) and `ActionLogPanel.handleOauthRespawn` (the "Re-open on Pi browser" button rendered when an OAuth URL appears in the action log). The form (`cloudflare-setup-form`) must NOT call `onShowVnc()` on POST resolve — pre-warming the fullscreen overlay before the OAuth URL is on the brand chromium hides the form, the ActionLogPanel, and the very button operators must click. The `[browser-viewer] event=mount surface="overlay"` line must appear within 5 s of `[device-url:click] navigateResult=ok`, never before.
+### Error envelope contract
+Every `POST /api/admin/cloudflare/setup` failure returns a `CloudflareSetupError` carrying — in addition to `field`, `message`, `output`, `correlationId`, `streamLogPath` — two structured fields the form relays into the chat as a fenced JSON block:
+- `inputsAlreadyHeld: { admin?: string; public?: string; apex?: string }` — the FQDNs the route composed from the submit body before `err()` fired. Pre-validation failures emit `{}` so absence is itself deterministic.
+- `discoveryResults: { tunnels: { id; name }[]; domains: string[] }` — the last-known snapshot from the process-lifetime `discoveryCache` Map that `GET /tunnels` and `GET /domains` write to on success.
+The chat relay appends both as a fenced ```` ```json ```` block under "Held by deterministic tools (do not re-solicit)". The admin agent's reply restates those values verbatim, names the literal error, and stops — re-soliciting is a doctrine violation. The retry-on-redeployment decision is owned by the route (2026-05-13 doctrine fix): `POST /api/admin/cloudflare/setup` looks up the most recent terminal `:Task {kind:"cloudflare-tunnel-login"}` on the conversation via `findMostRecentTerminalCloudflareTask`, and when the running bundle's mtime post-dates that Task's `completedAt` the respawn proceeds; otherwise the route returns the prior Task's `errorMessage` verbatim as the new envelope. The agent does not branch on `bundleMtime` and never narrates it (`[admin-reply-scrub]` records any leakage under `llm-narrates-internal-state`). The rule lives in IDENTITY.md § "Post-deterministic-error reply contract" and `.docs/agents.md` § "Intent Gate — post-deterministic-error reply contract". The shared `TunnelEntry` shape lives in [`platform/ui/app/lib/cloudflare-setup-types.ts`](../../ui/app/lib/cloudflare-setup-types.ts).
+## Identity model
+- **Product identity** (Maxy vs Real Agent) — known from `brand.json` (`productName`, `configDir`).
+- **Cloudflare account identity** — `cert.pem` from OAuth. One account per brand per device.
+- **Account binding drift** — `~/{configDir}/cloudflared/account-binding.json` is a historical drift marker. Reset via `reset-tunnel.sh` when switching accounts.
+## Discipline
+Loaded into IDENTITY.md § Cloudflare operations at install time. The short form: the agent's permitted surfaces are the two scripts, the three reference files, and plain `curl` reachability checks — everything else (Playwright, WebSearch-for-CF-recipes, Cloudflare API / SDK, ad-hoc `cloudflared` flag invention, direct edits to cert.pem / tunnel.state / config.yml / alias-domains.json) is out of bounds. Sanctioned-surface failures are reported with evidence and cited against `reset-guide.md`, not improvised around.

package/payload/platform/plugins/cloudflare/mcp/dist/index.d.ts ADDED Viewed

	@@ -0,0 +1,2 @@
1	+ export {};
2	+ //# sourceMappingURL=index.d.ts.map

package/payload/platform/plugins/cloudflare/mcp/dist/index.d.ts.map ADDED Viewed

	@@ -0,0 +1 @@
1	+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}