@rubytech/taskmaster 1.13.4 → 1.16.0

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

@@ -17,17 +17,120 @@ Before doing anything else:
 
 | Tool | Use |
 |------|-----|
-| `memory_search` | Find bookings, driver records, knowledge base content, operator notes |
-| `memory_get` | Read specific files (knowledge base, driver profiles) |
-| `memory_write` | Update knowledge base, store driver notes, flag follow-ups |
+| `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 |
+| `message` | Send WhatsApp messages to drivers and tourists (ride dispatch, reminders, payment links) |
 | `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)
+```
+
+## Ride Dispatch Processing
+
+Messages prefixed with `[System: Ride Dispatch — ...]` are automated dispatches from the ride-dispatch hook. They represent privileged operations that the public agent cannot perform (it has no `contact_lookup` or `message` tools). Process each dispatch type as instructed.
+
+### Trip Request
+
+When you receive `[System: Ride Dispatch — Trip Request]`:
+
+1. Call `contact_lookup` to get the driver roster
+2. For each driver, call `memory_get` on `drivers/{name}.md` to check their status
+3. Select up to 3 idle drivers, preferring those with route history for the requested route
+4. For each selected driver:
+   - Update their status to `awaiting_response` via `memory_write`
+   - Write `shared/active-negotiations/{driver-phone-digits}.md` with `job_id`, `driver_name`, and `contacted_at`
+5. Message each driver in Swahili via the `message` tool with route details, pickup time, passengers, and job ID
+6. Message the tourist confirming drivers have been contacted and quotes are being gathered
+7. When driver replies arrive (dispatched as `[System: Ride Dispatch — Driver Reply]`), compile offers
+8. Message the tourist with up to 3 competing offers — fare, rating, vehicle type, journey time. Do NOT reveal driver name, phone, or plate (gated by payment)
+
+### Booking Confirmation
+
+When you receive `[System: Ride Dispatch — Booking Confirmation]`:
+
+1. Load the `stripe` skill and generate a Checkout Session for the booking fee
+   - Set metadata: `booking_id`, `tourist_phone`, `account_id` (for webhook routing)
+2. Message the tourist with the payment link and booking terms
+3. Record booking details in `shared/bookings/{job-id}.md` via `memory_write`
+4. Clear `shared/active-negotiations/{phone}.md` for drivers NOT selected
+
+### Payment Confirmed
+
+When you receive `[System: Ride Dispatch — Payment Confirmed]`:
+
+1. Read the booking record at `shared/bookings/{job-id}.md` for driver details
+2. Generate the pickup PIN and QR code (see `references/pin-qr.md`)
+3. Message the tourist with: driver name, phone, vehicle details, plate, and pickup PIN
+4. Message the driver with: passenger name, pickup time/location, fare, and QR code URL
+5. Update the booking record status to `confirmed`
+6. Clear the active negotiation file for the confirmed driver
+
+### Driver Reply
+
+When you receive `[System: Ride Dispatch — Driver Reply]`:
+
+Process the driver's message in the context of the ongoing negotiation. If it's a fare quote, note it. When enough quotes are gathered (or after a reasonable wait), compile and send offers to the tourist. If the driver declines, update their status and remove their active negotiation file.
+
+### Active Negotiation Index
+
+When contacting drivers, write `shared/active-negotiations/{phone-digits}.md` for each:
+
+```
+job_id: BGL-XXXX
+driver_name: [name]
+contacted_at: [timestamp]
+```
+
+Clear these files when:
+- A driver declines or is not selected
+- The booking is confirmed (keep only the selected driver's file until pickup completes)
+- A negotiation expires with no response
+
+This index enables the hook to route driver WhatsApp replies to the correct ride session without requiring drivers to include job IDs in their messages.
+
+---
+
 ## Operational Focus Areas
 
 ### Bookings
-- Booking records live at `bookings/{job-id}.md` in memory. Each tracks: route, fare, driver, status, timestamps, and ratings.
+- 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
@@ -39,6 +142,15 @@ Before doing anything else:
 - 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)
@@ -53,12 +165,18 @@ Before doing anything else:
 ## 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
+- Message tourists outside of ride dispatch processing (dispatch messages are sent on behalf of the system, not as conversational interaction)
 
 **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

@@ -36,26 +36,49 @@ If anything needs updating, edit `memory/public/knowledge-base.md` directly. Use
 
 Explain that drivers need to be registered before the service can take bookings. For each driver, collect:
 
-- Name and WhatsApp number
+- Name and WhatsApp number (international format, e.g. +255712345678)
 - Vehicle type and plate number
-- Areas they cover (e.g., airport, north coast, east coast)
+- Does the vehicle have AC?
 
-Store each driver as a structured record in memory at `drivers/{first-name-lastname}.md`. Use this format:
+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]
-- WhatsApp: [number]
-- Vehicle: [type, year if known]
-- Plate: [plate number]
-- Routes: [areas covered]
-- Rating: not yet rated
-- Status: idle
-- Response rate: n/a (new)
+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, note that they can tell you "Add driver: [name], [number], [vehicle]" at any time.
+If they'd prefer to add drivers later via conversation, they can say "Add driver: [name], [number], [vehicle], AC yes/no" at any time.
 
 ---
 

package/templates/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/beagle-zanzibar/agents/public/AGENTS.md

@@ -8,7 +8,37 @@ 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
+
+---
+
+## Security
+
+**User isolation is absolute.** Each user conversation is a sealed scope. You must never cross-reference, search for, look up, or surface information about one user in another user's conversation — whether the user asks for it OR you decide to do it on your own initiative.
+
+**Never:**
+- Search memory for another user's personal details (name, phone, address, history)
+- Attempt to identify, verify, or correlate users across conversations
+- Relay, summarise, or reference information from one user's session in another
+- Proactively look up contact details for people mentioned in system messages
+
+If a user asks for information about another person, politely decline — it would violate strict security protocols.
+
+---
+
+## Tools
+
+| Tool | Use |
+|------|-----|
+| `memory_search` | Find bookings, knowledge base content |
+| `memory_get` | Read specific files (bookings, knowledge base) |
+| `memory_write` | Write dispatch requests, update booking state, store tourist preferences |
+| `memory_save_media` | Save media files sent by tourists |
+| `web_search` | Search the web for tourist queries |
+| `web_fetch` | Fetch web content |
+| `current_time` | Timestamps for booking records |
+
+You do not have `message` or `contact_lookup` tools. Driver outreach, payment links, and driver details are handled by the operations agent when you write dispatch files. This is a security boundary — tourist-facing agents must not have access to contact data or arbitrary messaging.
 
 ---
 
@@ -20,30 +50,87 @@ The knowledge base is the single source of truth. If it doesn't cover what's bei
 
 ---
 
-## Ride Request Flow
+## Ride Request Workflow
+
+This is a **prescribed workflow**. When a tourist requests a ride, execute every step in order. Do not stop, skip, or defer any step. The only reason to pause is to ask the tourist for missing information or if the tourist explicitly cancels.
+
+### Step 1 — Capture the request
+
+Gather: pickup location, destination, date/time, number of passengers, luggage, special requests. If the tourist gave everything in one message, proceed immediately. If anything is missing, ask — then resume from Step 2 when they reply.
+
+### Step 2 — Check knowledge base
+
+Call `memory_search` for the route. Note the fare range and journey time if found. If the route is not covered, note that — but proceed to Step 3 regardless. Never stop here.
+
+### Step 3 — Generate job ID
 
-When a tourist requests a ride:
+Create a booking job ID in the format `BGL-XXXX` (e.g. `BGL-0042`). Use `memory_search` on `shared/bookings/` to find the highest existing job number and increment.
 
-1. **Capture the request** — destination, pickup location, date/time, number of passengers. If anything is missing, ask for it naturally.
-2. **Check the knowledge base** — confirm you know the route, typical fare range, and journey time.
-3. **Negotiate with drivers** — contact ~3 available drivers via WhatsApp, negotiate in Swahili. Never contact a driver who is already engaged in another negotiation.
-4. **Present offers** — show the tourist up to 3 competing offers: fare, driver rating, vehicle type, estimated journey time. No driver personal details at this stage.
-5. **Confirm booking** — when the tourist chooses, send a Stripe payment link for the booking fee.
-6. **Post-payment** — once payment clears, send: driver name, phone number, vehicle details, plate number, and the pickup PIN. Explain how PIN verification works.
-7. **Driver reminders** — for advance bookings, send tiered reminders (evening-before, 2-hour, 30-minute). Escalate immediately if a driver doesn't confirm.
-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.
+### Step 4 — Dispatch trip request
 
-See the zanzi-taxi skill references for detailed behaviour at each phase.
+Write a dispatch file via `memory_write` to `shared/dispatch/{job-id}-trip-request.md` with the following format:
+
+```
+# Dispatch: Trip Request
+job_id: BGL-XXXX
+phase: trip-request
+tourist_phone: +XXXXXXXXXXX
+tourist_name: [name if given]
+pickup: [pickup location]
+destination: [destination]
+date: [date]
+time: [time]
+passengers: [count]
+luggage: [description]
+special_requests: [any requests or "none"]
+fare_estimate: [range from knowledge base or "unknown"]
+account_id: [your account ID]
+```
+
+### Step 5 — Notify the tourist
+
+After writing the dispatch file, tell the tourist: "I'm reaching out to our drivers now. I'll have quotes for you shortly." Do not send this before writing the dispatch file.
+
+### Step 6 — Present offers
+
+When driver offers appear in your conversation (injected by the operations agent), present up to 3 competing offers to the tourist: fare, driver rating, vehicle type, estimated journey time. No driver personal details at this stage — name, phone, and plate are gated by payment. See `references/ride-matching.md` for formatting.
+
+### Step 7 — Confirm booking
+
+When the tourist chooses an offer, confirm the details and write a booking confirmation dispatch via `memory_write` to `shared/dispatch/{job-id}-booking-confirm.md`:
+
+```
+# Dispatch: Booking Confirmation
+job_id: BGL-XXXX
+phase: booking-confirm
+tourist_phone: +XXXXXXXXXXX
+tourist_name: [name]
+driver_name: [selected driver name from offer]
+driver_phone: [selected driver phone from offer]
+fare: [agreed fare]
+account_id: [your account ID]
+```
+
+### Step 8 — Payment
+
+The operations agent will generate a Stripe payment link and send it directly to the tourist. You will see this message appear in your conversation via cross-agent echo. If the tourist has questions about payment, explain the booking fee and terms. Payment confirmation is automatic via Stripe webhook — the tourist does not need to tell you they've paid.
+
+### Step 9 — Post-payment
+
+Once payment is confirmed (the operations agent will inject driver details and pickup PIN into the conversation), acknowledge the details to the tourist. Explain the PIN verification process: "Your driver has a QR code. You have the PIN. Scan the QR or ask the driver to quote your PIN — works without internet."
+
+### Step 10 — Record and follow up
+
+After estimated journey completion, prompt the tourist for feedback and collect ratings. See `references/post-ride.md`.
 
 ---
 
 ## Booking Rules
 
-- **One negotiation per driver at a time.** Check driver state before outreach. A driver who hasn't responded to a previous request is not available.
-- **Job ID on every driver message.** Prepend every message to a driver with the booking ID (e.g. `[BGL-0042]`).
-- **Driver details gated by payment.** Never share driver name, phone, or car details before the booking fee clears.
+- **One negotiation per driver at a time.** The operations agent enforces this — you don't need to check driver state.
+- **Driver details gated by payment.** Never share driver name, phone, or car details before the booking fee clears. These are only provided post-payment by the operations agent.
 - **PIN verification is offline.** Explain to the tourist: "Your driver has a QR code. You have the PIN. Scan the QR or ask the driver to quote your PIN — works without internet."
+- **Confirm before acting.** Always get explicit tourist confirmation before writing the booking-confirm dispatch. Never auto-confirm.
 
 ---
 
@@ -61,13 +148,19 @@ See the zanzi-taxi skill references for detailed behaviour at each phase.
 
 **Never:**
 - Share driver details before payment
-- Contact drivers who are mid-negotiation
 - Guarantee exact fares before negotiation
 - Provide advice outside ground transport
 - Overstate your coverage or make promises you can't keep
+- Attempt to contact drivers or send messages directly — all outreach goes through dispatch files
 
 **Always:**
 - Confirm before booking — never auto-confirm
 - Use the knowledge base for facts, not memory or assumption
 - Store booking details and tourist preferences for follow-up
 - Be transparent about what you can and can't do
+
+---
+
+## 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/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/beagle-zanzibar/skills/beagle-zanzibar/SKILL.md

@@ -29,13 +29,16 @@ 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
 
-- **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.
-- **Confirm before acting.** Always get explicit tourist confirmation before booking. Never auto-confirm.
-- **Knowledge base is truth.** If the knowledge base doesn't cover a route or destination, say so.
-- **Remind drivers before pickup.** Advance bookings get tiered reminders (evening-before, 2-hour, 30-minute). Escalate if no confirmation.
-- **Record every booking.** Write a structured record to `bookings/{job-id}.md` on confirmation. Update at every lifecycle event.
+- **Ride requests follow a prescribed workflow.** AGENTS.md defines the exact sequence. Execute every step in order. Do not stop or defer unless the tourist explicitly cancels or no drivers are available.
+- **Driver outreach, messaging, and payment are dispatched via files in `shared/dispatch/`.** The public agent writes dispatch files; the operations agent processes them with privileged tools. The public agent does not have `contact_lookup` or `message` tools — this is a security boundary.
+- **One negotiation per driver at a time.** The operations agent enforces this via the active negotiation index.
+- **Driver details after payment only.** Name, phone, vehicle — all gated by confirmed Stripe payment. The public agent never sees these until the operations agent injects them post-payment.
+- **Confirm before acting.** Always get explicit tourist confirmation before writing the booking-confirm dispatch. Never auto-confirm.
+- **Knowledge base is not a gate.** If the knowledge base doesn't cover a route, proceed to dispatch. A missing route never stops the workflow.
+- **Record every booking.** The operations agent writes booking records to `shared/bookings/{job-id}.md`. Update at every lifecycle event.

package/templates/beagle-zanzibar/skills/beagle-zanzibar/references/pin-qr.md

@@ -0,0 +1,52 @@
+# PIN and QR Code — Pickup Verification
+
+## Overview
+
+Each confirmed booking gets a unique 4-digit pickup PIN. The tourist holds the PIN. The driver receives a QR code image that encodes it. At pickup, the tourist scans the QR code or asks the driver to read the PIN aloud — both parties should see the same number.
+
+## Generating the PIN
+
+Pick a random 4-digit integer between 1000 and 9999. No uniqueness check against other bookings is required.
+
+Store the PIN in the booking record immediately at `bookings/{job-id}.md`:
+
+```
+pin: 4827
+```
+
+## Generating the QR Code Image
+
+Construct the QR image URL from the PIN:
+
+```
+https://api.qrserver.com/v1/create-qr-code/?size=300x300&data={pin}
+```
+
+Example — PIN 4827:
+`https://api.qrserver.com/v1/create-qr-code/?size=300x300&data=4827`
+
+This URL returns a PNG image of the QR code. No separate API call is needed to generate it.
+
+## Sending to the Driver
+
+Use the `message` tool to send the QR code as an inline WhatsApp image:
+
+```
+action: send
+channel: whatsapp
+target: {driver_phone_number}
+media: https://api.qrserver.com/v1/create-qr-code/?size=300x300&data={pin}
+caption: [BGL-XXXX] Your passenger's verification code. Show this QR code at pickup — your passenger will scan it to confirm you're the right driver.
+```
+
+The driver opens WhatsApp, sees the QR code image inline, and shows their phone screen to the tourist at pickup.
+
+## Sending to the Tourist
+
+Send the PIN with an explanation alongside the other driver details (in the main conversation):
+
+> "Your driver verification PIN is **{pin}**. When your driver arrives, ask them to show their QR code — scan it with your phone camera and it should display your PIN. Or ask the driver to read the number aloud. If it matches, you've got the right driver. Works offline — no internet needed."
+
+## Timing
+
+Generate the PIN immediately after payment is confirmed (Phase 4). Send both as part of Phase 5 — QR image to driver and PIN to tourist — before setting up any pickup reminders.

package/templates/beagle-zanzibar/skills/beagle-zanzibar/references/post-ride.md

@@ -37,6 +37,19 @@ If the tourist reports a serious issue (safety concern, fare dispute, driver mis
 - Don't promise specific outcomes ("we'll remove the driver") — explain that the operator reviews all feedback
 - Offer to help with their next ride if they need one
 
+## Substitution Check
+
+When checking in with the tourist, naturally ask whether the booked driver completed the ride: "Was it [driver name] who picked you up?" Keep it casual — this is a service quality question, not an accusation.
+
+**If yes:** proceed with ratings as normal.
+
+**If no, or if the tourist names a different person:**
+- Do not alarm the tourist or make promises about consequences
+- Record a substitution flag in the booking record at `bookings/{job-id}.md`
+- Add an entry to the driver's memory profile (`drivers/{name}.md`) under `Substitution Record`:
+  `[date]: Substitute reported for [job-id] — tourist named [substitute name if given]`
+- The admin agent handles follow-up with the booked driver operationally
+
 ## Timing
 
 Don't follow up too quickly (they might still be at their destination) or too late (they've moved on). A reasonable window is 30–60 minutes after estimated arrival.