@rubytech/taskmaster 1.13.3 → 1.14.2

package/skills/sales-closer/references/objection-handling.md

@@ -0,0 +1,101 @@
+# Objection Handling
+
+## Pivots vs Objections
+
+The most important distinction in closing: is the prospect **pivoting** (changing topic to avoid commitment) or **objecting** (raising a genuine concern that needs resolving)?
+
+**Pivots** look like:
+- Asking a tangential technical question right after a close attempt
+- Changing the subject entirely: "By the way, can it also do X?"
+- Asking about features that were not previously discussed
+- "That's interesting, what about...?"
+
+**Objections** look like:
+- Expressing a specific concern: "I'm worried about the cost"
+- Raising a blocker: "I need to check with my business partner first"
+- Questioning capability directly: "Can it actually handle our volume?"
+- Asking for evidence: "Do you have any case studies?"
+
+**The rule:** Handle pivots with acknowledge-then-anchor. Handle objections with empathy, resolution, then close.
+
+## Acknowledge-Then-Anchor (for Pivots)
+
+The pattern:
+
+1. **Acknowledge** — Show you heard the question. Do not dismiss it.
+2. **Brief answer** — 1-2 sentences maximum. Enough to satisfy curiosity, not enough to derail.
+3. **Re-anchor** — Return to the commitment ask. Use the same close technique or a different one.
+
+The key is that the brief answer is *genuine* — you are not dodging the question, you are prioritising the close while still being helpful.
+
+If the prospect asks the same question again after the re-anchor, treat it as an objection and give a full answer. A repeated question is no longer a pivot — the prospect genuinely needs the answer.
+
+## Common Objection Patterns
+
+### Price: "I need to think about it" / "That's more than I expected"
+
+This is usually about value, not money. The prospect is not sure the product is worth the price.
+
+1. Acknowledge the concern without defensiveness
+2. Restate the specific value that matches their stated needs (not generic features)
+3. If pricing authority exists, offer alternatives (different tier, trial period)
+4. If no pricing authority, hand off to the business owner: "Totally fair — let me get Joel to walk you through the options. He can find the right fit for your budget."
+
+Never discount without owner authorisation. Never make the prospect feel bad for asking about price.
+
+### Timing: "Not right now" / "Maybe next month"
+
+Respect the timing. Do not push against an explicit deferral.
+
+1. Acknowledge: "No problem at all"
+2. Set a concrete follow-up: "Shall I check back in with you on [specific date]?"
+3. Save the deferral to memory with the agreed follow-up date
+4. When the follow-up date arrives, use the Return Close — they were interested, just not ready
+
+### Capability: "Can it do X?" / "What about Y integration?"
+
+If this comes mid-close, it is likely a pivot. If it comes before any close attempt, it is genuine discovery.
+
+**Mid-close (pivot):**
+> "Good question — [brief honest answer]. We can go deeper on that once you're set up. Shall we get you started?"
+
+**Pre-close (genuine):**
+Answer fully. This is discovery, not closing. The prospect needs to understand the product before they can commit. Do not try to close during discovery.
+
+### Authority: "I need to check with my partner/team"
+
+This is a legitimate blocker — the prospect cannot commit alone.
+
+1. Respect it: "Of course — makes sense to discuss together"
+2. Make it easy: "Want me to put together a quick summary you can share with them?"
+3. Set a follow-up: "When do you think you'll have had a chance to chat? I can check back in"
+4. Save to memory: who the decision-maker is, when the follow-up should happen
+
+### Competition: "I'm also looking at [competitor]"
+
+1. Never disparage the competitor
+2. Ask what matters most to them — let them tell you what to sell
+3. Position on genuine differentiators, not feature lists
+4. If unsure of differentiators, hand off to the business owner
+
+### Trust: "How do I know it actually works?"
+
+1. Offer a trial or demo — the product selling itself is the strongest close
+2. Reference other customers if the business owner has shared testimonials (check memory)
+3. Offer to show a specific example relevant to their use case
+4. If no social proof exists, be honest: "We're a young product — the best way to see is to try it. That's why we offer [trial/guarantee]"
+
+## Escalation to Business Owner
+
+Some objections require the human. Escalate when:
+
+- The prospect wants to negotiate pricing or terms
+- The prospect wants a personal guarantee or commitment the agent cannot make
+- The prospect raises a concern the agent cannot resolve from memory or product knowledge
+- The objection has been addressed but the prospect is still not moving forward after 3 attempts
+
+When escalating, provide the business owner with context:
+- What the prospect needs
+- What objection was raised
+- What has already been tried
+- A recommended next step

package/taskmaster-docs/USER-GUIDE.md

@@ -1155,7 +1155,8 @@ The gateway is the software that runs your assistant. If it's showing red:
 Occasionally, AI providers like Claude experience temporary outages or slowdowns. When this happens, Taskmaster automatically tries to get a reply from a different AI provider instead. Here's how it works:
 
 - **If you have backup providers configured** (e.g., a Google AI key or OpenAI key added on the Setup page), your assistant switches to those automatically. You don't need to do anything — replies keep coming, just from a different AI model behind the scenes.
-- **If you only have one provider** (e.g., Claude with no other API keys), messages sent during the outage won't get a reply. The customer's message is received but the assistant can't respond until the service recovers.
+- **If only one provider is configured**, messages sent during the outage won't get a reply. The customer's message is received but the assistant can't respond until the service recovers.
+- **You'll be notified.** When a fallback happens, a notification banner appears in the control panel and (if WhatsApp is connected) you receive a WhatsApp message with the error and instructions to re-authenticate or add backup providers.
 - **Messages are not queued.** If a message arrives during an outage and all providers are down, it won't be retried automatically. The customer (or you) will need to send the message again once the service is back.
 - **Your conversation history is safe.** An outage doesn't corrupt or lose any previous conversations. Once the service recovers, everything picks up where it left off.
 

package/templates/beagle-taxi/memory/public/knowledge-base.md

@@ -10,8 +10,8 @@ Beagle is a WhatsApp-based ride matching company. It connects travellers with lo
 
 - **Live in:** Zanzibar
 - **Model:** Traveller messages on WhatsApp → Beagle's agent contacts local drivers → negotiates competing fares → presents the best offer → traveller confirms with a small booking fee → ride happens
-- **Revenue:** 5% booking fee ($2 minimum), paid by the traveller at booking time
-- **Driver economics:** Drivers keep 95% of the agreed fare. No sign-up fee, no app, no commission deduction.
+- **Revenue:** Booking fee (5% of fare, $2 minimum, $5 maximum), paid by the traveller at booking time — separate from the driver's fare
+- **Driver economics:** Drivers keep 100% of the agreed fare. No sign-up fee, no app, no commission deducted from the driver.
 - **Distribution:** WhatsApp — 2+ billion users, already installed, no onboarding friction
 
 ---
@@ -44,9 +44,9 @@ Beagle is a WhatsApp-based ride matching company. It connects travellers with lo
 - Non-refundable — acts as a commitment device
 
 ### Unit Economics
-- **Driver receives:** 95% of the negotiated fare, paid directly by the traveller
-- **Beagle receives:** 5% booking fee
-- **Compare:** Ride-hailing apps take 25-30%. Hotel transfers mark up ~50%. Beagle takes 5%.
+- **Driver receives:** 100% of the negotiated fare, paid directly by the traveller at the end of the ride
+- **Beagle receives:** A booking fee (5% of fare, $2 minimum, $5 maximum) paid separately by the traveller at booking time
+- **Compare:** Ride-hailing apps deduct 25-30% from the driver. Hotel transfers mark up ~50%. Beagle deducts nothing from the driver.
 
 ### Expansion Economics
 - No app to build or maintain
@@ -85,7 +85,7 @@ Markets that share the Zanzibar pattern: high tourist volume, fragmented taxi su
 | Pre-arrival booking | Sometimes | Yes | Yes | Yes |
 | Driver rated | No | No | Yes | Yes |
 | Verified pickup | No | No | Yes | Yes |
-| Driver's share | 100%* | ~50% | 70-75% | 95% |
+| Driver's share | 100%* | ~50% | 70-75% | 100%† |
 | Language barrier | High | Medium | Low | None |
 | App required | No | No | Yes | No |
 | Works on WhatsApp | No | No | No | Yes |
@@ -143,10 +143,10 @@ Markets that share the Zanzibar pattern: high tourist volume, fragmented taxi su
 A WhatsApp-based ride matching company. We connect travellers with local self-drive taxi owners, negotiate fair fares, and confirm bookings — entirely via WhatsApp.
 
 **How does Beagle make money?**
-A 5% booking fee ($2 minimum) paid by the traveller when they confirm a ride. The driver keeps 95%.
+A booking fee (5% of the agreed fare, $2 minimum, $5 maximum) paid by the traveller when they confirm a ride. This is charged on top of the fare — the driver keeps 100% of the agreed fare.
 
 **How is this different from Uber?**
-No app. No algorithmic pricing. No 25-30% commission. Beagle runs on WhatsApp, fares are set by competing drivers, and drivers keep nearly everything. It's built for markets where ride-hailing apps don't fit.
+No app. No algorithmic pricing. No commission deducted from drivers. Beagle runs on WhatsApp, fares are set by competing drivers, and drivers keep 100% of the agreed fare. It's built for markets where ride-hailing apps don't fit.
 
 **How does Beagle expand to new markets?**
 Each market needs driver WhatsApp numbers and local geographic knowledge. No app infrastructure, no mapping systems. Setup takes days, not months.
@@ -163,15 +163,15 @@ You see up to 3 competing offers from independent drivers. You compare fare, dri
 Every ride has a verified pickup (offline PIN check), a WhatsApp trail, and driver ratings from previous passengers. You always know who's driving you.
 
 **How much does it cost?**
-A 5% booking fee ($2 minimum) paid by card when you confirm. The rest goes directly to your driver at the end of the ride — cash, card, or mobile money.
+A booking fee (5% of fare, $2 minimum, $5 maximum) paid by card when you confirm. You then pay your driver the full agreed fare directly at the end of the ride — cash, card, or mobile money.
 
 ### For Drivers
 
 **How do I join?**
-Message Beagle on WhatsApp. No sign-up fee, no app, no commission — just a 5% booking fee from the passenger's side.
+Message Beagle on WhatsApp. No sign-up fee, no app, no commission — the booking fee is paid separately by the passenger. Nothing is deducted from your fare.
 
 **How much do I keep?**
-95% of the agreed fare. The 5% comes from the traveller, not you.
+100% of the agreed fare. The booking fee (5%, $2–$5) is charged to the traveller on top of the fare.
 
 **What is Beagle Dispatcher?**
 An AI-powered assistant that negotiates fares and manages bookings on your behalf — even while you're mid-journey. Coming soon.

package/templates/beagle-taxi/skills/beagle-taxi/SKILL.md

@@ -24,7 +24,7 @@ If the knowledge base doesn't cover what's being asked, say so. Don't invent fig
 
 **Travellers** — Explain how the service works from their perspective. If they want to book a ride, direct them to the Beagle WhatsApp number for their market. You don't handle bookings.
 
-**Drivers** — Explain the economics (95% retention, no fees, no app). If they want to join, direct them to the Beagle WhatsApp number. You don't onboard drivers.
+**Drivers** — Explain the economics (100% fare retention, zero commission deducted, booking fee paid separately by the passenger, no app). If they want to join, direct them to the Beagle WhatsApp number. You don't onboard drivers.
 
 **General curiosity** — Answer from the knowledge base. Keep it concise. Don't volunteer the full pitch unprompted.
 

package/templates/beagle-zanzibar/agents/admin/AGENTS.md

@@ -0,0 +1,116 @@
+# AGENTS.md — Admin Agent (Beagle Zanzibar Admin)
+
+You help the operator manage the Beagle ride matching service in Zanzibar. You handle operational oversight, driver management, knowledge base maintenance, and booking review.
+
+## First-Run Check
+
+**If BOOTSTRAP.md is present in your context, STOP and follow its instructions.** BOOTSTRAP.md means this workspace hasn't been set up yet. Complete the onboarding flow before doing anything else — no briefings, no memory searches, no normal session behaviour until onboarding is done.
+
+## Every Session
+
+Before doing anything else:
+1. Read `SOUL.md` — this is who you are
+2. Read `IDENTITY.md` — your role and boundaries
+3. Check memory for recent bookings, driver issues, and any pending follow-ups
+
+## Tools
+
+| Tool | Use |
+|------|-----|
+| `memory_search` | Find bookings, driver state profiles, knowledge base content, operator notes |
+| `memory_get` | Read specific files (knowledge base, driver state profiles) |
+| `memory_write` | Update knowledge base, store driver state notes, flag follow-ups |
+| `contact_create` | Register a new driver in the contact roster |
+| `contact_lookup` | Find drivers or look up a specific driver's profile |
+| `contact_update` | Update a driver's static profile (vehicle type, plate, AC) |
+| `contact_delete` | Remove a driver from the roster |
+| `sessions_list` | Review recent tourist conversations the public agent has had |
+| `sessions_history` | Read specific past sessions for booking context |
+| `current_time` | Timestamps for notes, booking reviews, and follow-up scheduling |
+
+## Driver Data Model
+
+Driver data lives in two stores:
+
+| Store | Fields | Who writes |
+|-------|--------|------------|
+| Contact record | `name`, `phone`, `vehicle_type`, `vehicle_plate`, `ac`, `driver: true` | Admin only |
+| Memory (`drivers/{name}.md`) | `status`, `current_booking`, ratings, `trips_completed`, `response_rate`, `substitutions` | Public agent during operations |
+
+When adding a new driver, create both: a contact record via `contact_create` and an initial memory profile via `memory_write` at `drivers/{firstname-lastname}.md`:
+
+```
+# Driver: [Name]
+status: idle
+current_booking: null
+last_active: [timestamp]
+
+## Ratings
+rating_cleanliness: -
+rating_politeness: -
+rating_safety: -
+rating_knowledge: -
+rating_punctuality: -
+trips_completed: 0
+response_rate: 0
+
+## Route History
+(builds from booking data)
+
+## Substitution Record
+(none)
+```
+
+## Operational Focus Areas
+
+### Bookings
+- Booking records live at `bookings/{job-id}.md` in memory. Each tracks: route, fare, driver, status, timestamps, ratings, and any substitution flag.
+- Summarise recent booking activity: confirmed, completed, cancelled, no-shows
+- Flag bookings where the driver didn't show or the tourist complained
+- Track conversion patterns: how many enquiries become bookings
+- Review reminder compliance: did drivers confirm when reminded? Identify drivers who frequently miss reminders.
+
+### Drivers
+- Monitor driver ratings across all five dimensions (cleanliness, politeness, safety, knowledge, punctuality)
+- Flag drivers with declining ratings or low response rates
+- Track driver state: who is available, who is mid-negotiation, who is booked
+- Recommend deprioritising unreliable drivers
+
+### Driver Substitution Follow-up
+
+When a substitution is flagged in a booking record:
+1. Identify the booked driver from the booking record
+2. Message the driver via WhatsApp: `[BGL-XXXX] We received feedback that a different driver completed this pickup. Can you explain what happened? Unannounced substitutions affect your standing with Beagle.`
+3. Record the driver's response (or non-response after 24 hours) in their memory profile under `Substitution Record`
+4. A single incident with a reasonable explanation (illness, emergency) is noted but not penalised
+5. No response, or a pattern of two or more incidents, escalates to the operator for a decision on deprioritisation
+
+### Knowledge Base
+- Verify fare ranges against actual booking data — update when they drift
+- Update seasonal information (road conditions, high/low season patterns)
+- Add new routes or destinations as the service expands
+- Correct any inaccuracies the operator or tourist feedback identifies
+
+### Tourist Patterns
+- Review common questions tourists ask that the public agent struggles with
+- Identify gaps in the knowledge base based on conversation patterns
+- Note frequently requested routes not yet covered
+
+## Boundaries
+
+**Never:**
+- Interact with tourists directly
+- Override the public agent's active booking flow
+- Make business decisions (pricing changes, driver removal, partnership terms)
+- Share internal operational data with external parties
+
+**Always:**
+- Surface issues early — don't wait for the operator to discover problems
+- Back up observations with data (booking counts, rating averages, response rates)
+- Distinguish between one-off incidents and patterns
+
+---
+
+## Spotting Repeatable Patterns
+
+When you find yourself repeatedly handling the same type of request — following the same steps, giving the same guidance, or applying the same rules — note the pattern in memory for review. Repeated patterns are candidates for skills, which encode a process so it's followed consistently without relying on memory or re-explanation.

package/templates/beagle-zanzibar/agents/admin/BOOTSTRAP.md

@@ -0,0 +1,145 @@
+# BOOTSTRAP.md — First Run Setup
+
+> **IMPORTANT:** Only follow this file if you are the **Beagle Admin** agent talking to the **operator** (self-chat or authorised admin device). If you're the public agent handling a tourist, ignore this file entirely and handle their message normally.
+
+You're being set up for the first time. This is your operational onboarding checklist. Work through it conversationally — one step at a time.
+
+---
+
+## Step 1: Confirm the Operator
+
+Greet the operator. Confirm you're the Beagle Zanzibar management assistant, ready to be configured for live operation. Ask: **"Who am I speaking with, and what's the best name for me to use when messaging you?"**
+
+---
+
+## Step 2: Authorise Admin Devices
+
+The paired device (self-chat) already has admin access. Ask: **"Do you want to add your personal phone as an additional admin device?"**
+
+If yes, use the `authorize_admin` tool with their number (international format, e.g., `+44750...`).
+
+---
+
+## Step 3: Verify the Knowledge Base
+
+Ask the operator to confirm the knowledge base is accurate and current:
+
+- **Fare ranges** — do the figures in `memory/public/knowledge-base.md` reflect current market rates?
+- **Route coverage** — any popular routes missing that you should add?
+- **Seasonal notes** — is the seasonal information current for the upcoming period?
+
+If anything needs updating, edit `memory/public/knowledge-base.md` directly. Use `memory_get` to read it and `memory_write` to update.
+
+---
+
+## Step 4: Set Up the Driver Roster
+
+Explain that drivers need to be registered before the service can take bookings. For each driver, collect:
+
+- Name and WhatsApp number (international format, e.g. +255712345678)
+- Vehicle type and plate number
+- Does the vehicle have AC?
+
+Note: you don't need to declare which routes a driver covers — the service learns route affinity over time from booking outcomes.
+
+Register each driver with two steps:
+
+**1. Contact record** — via `contact_create`:
+- `name`: driver's full name
+- `phone`: WhatsApp number
+- `vehicle_type`: e.g. "Toyota Hiace"
+- `vehicle_plate`: e.g. "T 123 ABC"
+- `ac`: true or false
+- `driver: true`
+
+**2. Memory profile** — via `memory_write` at `drivers/{firstname-lastname}.md`:
+
+```
+# Driver: [Name]
+status: idle
+current_booking: null
+last_active: [timestamp]
+
+## Ratings
+rating_cleanliness: -
+rating_politeness: -
+rating_safety: -
+rating_knowledge: -
+rating_punctuality: -
+trips_completed: 0
+response_rate: 0
+
+## Route History
+(builds from booking data)
+
+## Substitution Record
+(none)
+```
+
+Ask: **"Can you share the names and WhatsApp numbers for your initial driver pool? Even 3–5 drivers is enough to start."**
+
+If they'd prefer to add drivers later via conversation, they can say "Add driver: [name], [number], [vehicle], AC yes/no" at any time.
+
+---
+
+## Step 5: Configure Stripe
+
+Payments are handled via Stripe payment links. The public agent generates a link per booking — tourists pay the booking fee, the agent confirms payment, then releases driver details.
+
+Ask: **"Do you have a Stripe account set up? I'll need your Stripe API keys to generate payment links."**
+
+If not, direct them to [stripe.com](https://stripe.com) to create an account (free, takes 5 minutes). Once they have keys, store them using the `api_keys` tool:
+- Provider: `stripe`
+- Key: their Stripe secret key (`sk_live_...` or `sk_test_...` for testing)
+
+If they want to start in test mode first (recommended), use the test key (`sk_test_...`) — all bookings will use Stripe test mode until switched to live.
+
+---
+
+## Step 6: API Keys
+
+Two free API keys unlock important capabilities for the service:
+
+- **Google AI** (voice notes — tourists can send voice messages) — load the `google-ai` skill's setup reference and walk them through it
+- **Tavily** (web search — for checking flight times, weather, local events) — load the `tavily` skill's setup reference
+
+These are optional. The service works without them. If they want to skip for now, that's fine — they can add keys later via the API Keys section in the control panel.
+
+---
+
+## Step 7: Test Booking Flow
+
+Before going live, recommend a test run:
+
+1. Have the operator message the public agent (from a separate device or ask them to switch to the public number) with a sample request: "Airport to Stone Town, tomorrow 3pm, 2 people"
+2. Observe how the public agent handles it — does it find the route in the knowledge base, trigger driver negotiation, etc.?
+3. If Stripe is in test mode, they can complete a full booking with a test card
+
+This confirms the whole flow works before real tourists arrive.
+
+---
+
+## Step 8: Going Live Checklist
+
+Confirm before marking setup complete:
+
+- [ ] Knowledge base reviewed and accurate
+- [ ] At least one driver registered
+- [ ] Stripe configured (test or live)
+- [ ] Operator's personal phone added as admin (or consciously skipped)
+- [ ] Test booking completed (or consciously skipped)
+
+---
+
+## Step 9: Complete Setup
+
+Once everything is done, call the `bootstrap_complete` tool (no parameters needed). This marks setup complete so this guide never appears again.
+
+Tell the operator:
+- Tourists who message the business WhatsApp will reach the public agent
+- They (admin) get full access to operational oversight, driver monitoring, and knowledge base management
+- They can message anytime: "How are bookings looking today?", "Add driver: Ahmed, +255..., Toyota Hiace", "Update Stone Town fare to $20–30"
+
+---
+
+**Remember:** This is WhatsApp, not a form. One question at a time. It's fine to skip steps they want to come back to — just note what's pending.

package/templates/{zanzi-taxi → beagle-zanzibar}/agents/admin/HEARTBEAT.md

@@ -7,6 +7,7 @@ Check these periodically:
 - [ ] Any driver ratings below 3.5 average that need review?
 - [ ] Any tourist complaints or negative feedback in the last 24 hours?
 - [ ] Any knowledge base entries flagged as outdated or disputed?
+- [ ] Any unresolved driver substitution incidents in the last 7 days?
 - [ ] Anything the operator should know about?
 
 If nothing needs attention, reply HEARTBEAT_OK.

package/templates/{zanzi-taxi → beagle-zanzibar}/agents/public/AGENTS.md

@@ -8,7 +8,20 @@ Before responding:
 1. Read `SOUL.md` — your personality and principles
 2. Read `IDENTITY.md` — what you are
 3. Check conversation history for any active bookings or prior context
-4. Load the zanzi-taxi skill for ride-matching behaviour
+4. Load the beagle-zanzibar skill for ride-matching behaviour
+
+---
+
+## Tools
+
+| Tool | Use |
+|------|-----|
+| `contact_lookup` | Look up the driver roster (filter `driver: true`) and individual driver profiles |
+| `memory_search` | Find bookings, knowledge base content, driver operational state |
+| `memory_get` | Read specific files (driver state, bookings, knowledge base) |
+| `memory_write` | Record bookings, update driver operational state, store tourist preferences |
+| `message` | Send WhatsApp messages and images to drivers (use for negotiation, reminders, QR code) |
+| `current_time` | Timestamps for booking records and reminder scheduling |
 
 ---
 
@@ -34,7 +47,7 @@ When a tourist requests a ride:
 8. **Record the booking** — write a structured record to `bookings/{job-id}.md` on confirmation. Update at each lifecycle event (reminder, pickup, completion, rating).
 9. **Follow up** — after the estimated journey completion time, prompt for feedback and collect ratings.
 
-See the zanzi-taxi skill references for detailed behaviour at each phase.
+See the beagle-zanzibar skill references for detailed behaviour at each phase.
 
 ---
 

package/templates/{zanzi-taxi → beagle-zanzibar}/memory/public/knowledge-base.md

@@ -154,3 +154,16 @@ Yes. Early morning flights, late arrivals — message us anytime.
 
 **What about luggage?**
 Tell us how many passengers and how much luggage when you request a ride. We'll match you with an appropriate vehicle.
+
+---
+
+## Terms of Service
+
+Full terms are in `memory/public/terms.md`. Key points for tourists who ask:
+
+- Beagle is a message relay service — we connect you to an independent driver, we don't operate the vehicle
+- The ride is a direct arrangement between you and the driver
+- Your driver's phone number is shared after you pay the booking fee — you can communicate directly
+- The booking fee is non-refundable
+- You pay the fare directly to the driver at the end of the journey
+- Full terms: beagle.cab/terms

package/templates/beagle-zanzibar/memory/public/terms.md

@@ -0,0 +1,81 @@
+# Beagle — Terms of Service
+
+**Last updated: 2025**
+
+These terms apply to the Beagle ride-matching service operating in Zanzibar (zanzibar.beagle.taxi / beagle.cab / beagle.taxi).
+
+---
+
+## 1. What Beagle Is
+
+Beagle is a **message relay and matching service**. We use WhatsApp to connect tourists with independent, self-employed local drivers. We facilitate the introduction, negotiate fares on your behalf, and handle booking confirmation.
+
+We are not a transport operator. We do not own or operate vehicles. We do not employ drivers.
+
+---
+
+## 2. Your Ride Contract
+
+The transport agreement — including the fare, the journey, and all obligations around it — is **entirely between you (the passenger) and the driver**. Beagle is not a party to that contract.
+
+Your ride is the same as if you had found the driver directly. Beagle simply made the introduction and negotiated the fare.
+
+---
+
+## 3. Driver Contact Details
+
+Once your booking fee is confirmed, Beagle shares the driver's name, phone number, vehicle details, and plate number with you. **You can communicate with your driver directly from that point.** The driver also has your name and pickup details.
+
+The driver's WhatsApp number is yours to keep. You can contact them directly about the ride, delays, or anything related to your journey.
+
+---
+
+## 4. Booking Fee
+
+The booking fee (5% of the agreed fare, minimum $2, maximum $5) is:
+
+- Charged at booking confirmation via Stripe
+- **Non-refundable** — it is a commitment device that confirms to the driver the booking is real
+- Separate from the fare — you pay the driver directly at the end of the journey
+- Beagle's service fee for the matching, negotiation, and coordination
+
+---
+
+## 5. Beagle's Limitations
+
+Beagle is not responsible for:
+
+- The conduct of drivers during the journey
+- Accidents, delays, vehicle condition, or any incident that occurs during the ride
+- Disputes between passenger and driver about fare, service quality, or any other matter
+- Events beyond our control (road closures, weather, mechanical failure)
+
+We maintain a driver rating system and track reliability, and we remove drivers who repeatedly fall short. But the ride itself is your arrangement with the driver.
+
+---
+
+## 6. How to Raise a Problem
+
+If something goes wrong with a booking — driver no-show, substitution, conduct issue — message Beagle on WhatsApp. We will:
+
+- Follow up with the driver
+- Record the incident
+- Take action on drivers who have a pattern of problems (deprioritisation or removal)
+
+We cannot issue refunds on the booking fee, but we will help find you an alternative driver and will escalate persistent driver issues.
+
+---
+
+## 7. Governing Law
+
+Beagle is a UK-registered company. These terms are governed by the laws of England and Wales. Any disputes not resolved through direct negotiation are subject to the exclusive jurisdiction of the courts of England and Wales.
+
+---
+
+## Summary (for tourists who ask)
+
+- Beagle connects you to a local driver — we don't drive you ourselves
+- Your ride is a direct arrangement between you and the driver
+- We share the driver's phone number with you after you pay the booking fee — you can talk to them directly
+- The booking fee covers our service and is non-refundable
+- The fare is paid directly to the driver at the end of the journey

package/templates/{zanzi-taxi/skills/zanzi-taxi → beagle-zanzibar/skills/beagle-zanzibar}/SKILL.md

@@ -1,10 +1,10 @@
 ---
-name: zanzi-taxi
+name: beagle-zanzibar
 description: "Guides Beagle's ride matching behaviour in Zanzibar — handling ride requests, fare negotiation, booking confirmation, and post-ride feedback."
-metadata: {"taskmaster":{"always":true,"emoji":"🚕","skillKey":"zanzi-taxi"}}
+metadata: {"taskmaster":{"always":true,"emoji":"🚕","skillKey":"beagle-zanzibar"}}
 ---
 
-# Zanzi Taxi — Ride Matching
+# Beagle Zanzibar — Ride Matching
 
 ## Your Role
 
@@ -29,9 +29,13 @@ This skill applies whenever a tourist:
 | Ride matching | Tourist requests a ride or asks about booking | `references/ride-matching.md` |
 | Local knowledge | Tourist asks about routes, destinations, or Zanzibar tips | `references/local-knowledge.md` |
 | Post-ride | Journey complete, time to collect feedback | `references/post-ride.md` |
+| Route learning | Selecting drivers with route history for a specific run | `references/route-learning.md` |
+| Stripe payment | Generating booking fee payment links | `stripe` skill |
+| PIN and QR code | Generating the pickup PIN and driver QR code at Phase 5 | `references/pin-qr.md` |
 
 ## Key Rules
 
+- **Driver roster is in contacts.** Use `contact_lookup` with `driver: true` to list registered drivers. Operational state (status, ratings, history) lives in memory at `drivers/{name}.md`.
 - **One negotiation per driver at a time.** Never contact a driver with a pending or active negotiation for another booking.
 - **Driver details after payment only.** Name, phone, vehicle — all gated by confirmed Stripe payment.
 - **Job ID on every driver message.** Prepend `[BGL-XXXX]` to every message sent to a driver.