@rubytech/create-sitedesk-code 0.1.340

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

@@ -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)
+- `sessionId`: 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/scheduling.md

@@ -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/site-lead-intake.md

@@ -0,0 +1,52 @@
+# Managing site form submissions (the published-site → D1 inbound channel)
+
+The business's published website has a contact / enquiry form, and that form is a **primary inbound-enquiry channel** — equal to phone and WhatsApp, not a side channel. Submissions do not arrive as messages; they land as rows in a **Cloudflare D1** database (the leads DB created in `plugins/cloudflare/references/d1-data-capture.md`). Nothing surfaces them automatically. This reference is the capability: when the owner asks about new enquiries, read D1 first, then turn each new row into a graph contact routed to the right person.
+
+The failure this prevents is concrete: asked "any new sign-ups?", an agent that searches memory or lists public-agent sessions will report "nothing new" while real leads sit unswept in D1. Memory and public-agent sessions are not where site enquiries live. **D1 is.**
+
+---
+
+## "Any new sign-ups / contacts / enquiries?" → read D1 first
+
+When the owner asks whether anything new has come in — sign-ups, contacts, enquiries, leads — the **first action is a D1 read of the leads DB**, before `memory_search`, before `contact_lookup` sweeps, before any public-agent `session-list`. The unswept set is the answer:
+
+```bash
+CLOUDFLARE_API_TOKEN="${MINTED_PAGES_D1}" wrangler d1 execute <db-name> --remote --json --command \
+  "SELECT id, name, email, message, created_at FROM leads WHERE swept = 0 ORDER BY id;"
+```
+
+This composes `plugins/cloudflare/references/d1-data-capture.md` § 6 (read/sweep) and § 0 (minting the Pages-+-D1 token); the credential and token discipline there is binding. Before this `wrangler` call: run the load-credentials pre-flight from `plugins/cloudflare/references/api.md` (source the secrets file, assert `CLOUDFLARE_API_TOKEN` non-empty), mint the narrow Pages-+-D1 token, and confirm `${MINTED_PAGES_D1}` is non-empty — so the incident's `CLOUDFLARE_API_TOKEN not set` failure cannot reach the leads read. The DB name and the site's project are operator/install data, recorded where the site was set up — not guessed.
+
+**Outcome contract for the answer:** the transcript shows a D1 round-trip (`wrangler d1 execute … SELECT … WHERE swept = 0`) as the response to "any new sign-ups?", not a memory search. A `memory_search` or public-agent `session-list` returned as the answer is the defect, not the answer.
+
+---
+
+## Each unswept row → dedupe, create-or-update, then route
+
+For every row in the unswept set, in order:
+
+1. **Dedupe against the graph.** Look the person up by the identifiers the row actually carries. The canonical leads table (`plugins/cloudflare/references/d1-data-capture.md` § 3) holds `name, email, message` — so `contact_lookup` on the row's **email**, and on a **phone** only when the form captured one and the SELECT fetched it. Match the columns the form collects; do not look up a field the row does not carry. A match means update; no match means create.
+2. **Create or update the contact.** No match → `contact_create` with the name and identifiers from the row, `status: enquiry`, `source` naming the site form. Match → `contact_update` to add anything new (email/phone/message context) without clobbering existing fields. Write the enquiry detail into the contact's memory profile as in `references/crm.md`.
+3. **Route to the install's recorded front-line owner** (below).
+4. **Sweep the row only after the graph write is confirmed.** Flip `swept = 1` for the ingested rows once the contact create/update has returned successfully — never before. An unconfirmed write followed by a sweep loses the lead silently.
+
+```bash
+CLOUDFLARE_API_TOKEN="${MINTED_PAGES_D1}" wrangler d1 execute <db-name> --remote --command \
+  "UPDATE leads SET swept = 1 WHERE swept = 0;"
+```
+
+A row is the durable record until it is swept; the sweep is the commit, and it follows the graph write, not the other way round.
+
+---
+
+## Front-line-owner routing is operator data, never a baked name
+
+A new site lead is assigned to the install's **recorded front-line owner** — the person enquiries route to for first contact and follow-up. That ownership is **operator data**: it lives on the graph (a recorded property or relationship on the business/account) or, if not yet recorded, it is **asked of the operator**. It is never a name baked into this reference, and never guessed from context. Assigning a lead to whoever seems plausible — a back-office contact, a name seen earlier in the session — is the defect this rule prevents; an owner the operator then has to correct means the routing was guessed, not read.
+
+If the front-line owner is not recorded on the install, ask the operator who new enquiries should go to and record it, then route. (Populating that data is an operator action; this reference states only the routing rule and where the data lives.)
+
+---
+
+## Why D1, not memory
+
+Memory profiles and public-agent sessions describe people the business already talks to. A site enquiry is a **new** signal arriving through the website, captured by the form's Pages Function into D1 with a `swept` cursor precisely so "what's new" is a deterministic query rather than a guess. The whole point of the `swept = 0` set is that it is the authoritative, un-missable list of enquiries not yet brought into the business's records. Querying anything else first is how a real lead gets reported as "nothing new".

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

@@ -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 `work-create`. Always pass `sessionKey` (from your system prompt — "Current session key: ...") to link the task to the current conversation automatically:
+
+```
+work-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 `work-update` to change name, description, status, priority, due date, or append a progress note:
+
+```
+work-update {
+  taskId: "<id>",
+  name: "Corrected task name",
+  note: "Renamed to reflect actual scope"
+}
+```
+
+```
+work-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 `work-complete` as a shorthand — it sets status to `completed` and appends a closing note:
+
+```
+work-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
+
+```
+work-list { status: "active" }
+work-list { status: "pending" }
+```
+
+### Get a specific task
+
+```
+work-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 `work-update` to set `status: "active"` and note the resumption
+3. Pass `sessionKey` in `work-create` for any new tasks in the new session — it links them to the current conversation automatically
+
+A task can span multiple sessions. Use `work-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.