@rubytech/taskmaster 1.13.4 → 1.16.0

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

@@ -1,36 +1,42 @@
 # Ride Matching — Booking Flow
 
-## Phase 1: Capture the Request
+> **This is a prescribed workflow.** AGENTS.md defines the step-by-step sequence. This reference provides detail for each step. The workflow has no discretionary exit points — execute every step unless the tourist cancels or no drivers are available.
 
-When a tourist messages about a ride, gather:
+## Capture (AGENTS.md Steps 1–3)
+
+Required fields:
 
 1. **Pickup location** — airport, hotel name, area
 2. **Destination** — where they're going
 3. **Date and time** — when they need the ride
 4. **Passengers** — how many people
-5. **Luggage** - how many pieces, anythinbg oversized
-6. **Special Requests*** - e.g. wheelchair access
+5. **Luggage** — how many pieces, anything oversized
+6. **Special requests** — e.g. wheelchair access
+
+Ask naturally, not as a form. If they give everything in one message, proceed immediately.
+
+The knowledge base check (Step 2) is informational — it gives you fare context. Whether the route is covered or not, proceed to dispatch.
 
-Ask naturally, not as a form. If they give you everything in one message ("Airport to Stone Town, Tuesday 3pm, 2 people"), acknowledge and proceed. If anything is missing, ask for it conversationally.
+After capturing the request, generate a job ID (BGL-XXXX) by checking `shared/bookings/` for the next available number.
 
-Check the knowledge base to confirm you know the route. If the route isn't covered, be honest — explain you're expanding coverage and can still try to find a driver, but can't give a reliable fare estimate.
+## Dispatch Trip Request (AGENTS.md Step 4)
 
-## Phase 2: Driver Negotiation
+Write a dispatch file to `shared/dispatch/{job-id}-trip-request.md` via `memory_write`. The operations agent will:
 
-Before contacting drivers:
-- Check driver states — only contact drivers marked as `idle`
-- Select ~3 drivers based on: rating, response rate, route familiarity, availability
-- Prepend every message with the job ID: `[BGL-XXXX]`
+1. Look up the driver roster via `contact_lookup`
+2. Check each driver's status in memory
+3. Select up to 3 idle drivers, preferring those with route history
+4. Message each driver in Swahili with route details, pickup time, passengers, and job ID
+5. Message the tourist confirming drivers have been contacted
 
-Negotiate in Swahili. The driver quotes their fare for the route. Collect responses and compare.
+You do not perform these steps directly — the dispatch file triggers them automatically.
 
-Tell the tourist you're finding them offers. Set expectations: "Let me contact drivers now. I'll have offers for you shortly."
+After writing the dispatch, tell the tourist you're reaching out to drivers (Step 5).
 
-If no drivers respond within a reasonable time, tell the tourist honestly. Offer to try again or suggest an alternative time.
+## Present Offers (AGENTS.md Step 6)
 
-## Phase 3: Present Offers
+When driver offers appear in your conversation (injected by the operations agent via cross-agent echo), present up to 3 competing offers. For each:
 
-Show up to 3 competing offers. For each:
 - **Fare** (what the tourist pays the driver)
 - **Driver rating** (aggregate score and trip count)
 - **Vehicle** (type, AC availability)
@@ -42,49 +48,42 @@ Frame it as a choice: "Here are your options — which works best?" Don't pressu
 
 If only one driver responded, present it honestly: "One driver available for this route. Here's the offer."
 
-## Phase 4: Booking Confirmation
+## Booking Confirmation (AGENTS.md Step 7)
 
 When the tourist chooses an offer:
+
 1. Confirm the details: route, time, fare, vehicle
-2. Explain the booking fee: "A small booking fee of [amount] confirms your ride. You pay [remaining fare] directly to your driver at the end."
-3. Send the Stripe payment link
-4. Wait for payment confirmation — do not proceed until Stripe confirms
+2. Write a booking confirmation dispatch to `shared/dispatch/{job-id}-booking-confirm.md` via `memory_write`
 
-## Phase 5: Post-Payment
+The operations agent will then:
+- Generate a Stripe Checkout Session with the booking fee
+- Send the payment link directly to the tourist
+- Record booking details in `shared/bookings/{job-id}.md`
 
-Once payment clears, send the tourist:
-- Driver name
-- Driver phone number
-- Vehicle description and plate number
-- Pickup PIN (4-digit code)
-- Explanation: "Your driver has a QR code. Scan it with your phone camera to see the PIN, or ask the driver to quote it. If it matches your PIN, you've got the right driver. Works offline — no internet needed."
+## Payment and Post-Payment (AGENTS.md Steps 8–9)
 
-Confirm the driver has received:
-- Passenger name
-- Pickup time and location
-- Fare confirmed
-- QR code (encodes the tourist's PIN)
+Payment confirmation is automatic — Stripe sends a webhook when the tourist completes payment. The operations agent processes this and:
 
-## Phase 6: Driver Pickup Reminders
+1. Generates the pickup PIN and QR code
+2. Messages the tourist with driver details and PIN
+3. Messages the driver with passenger details and QR code
+4. Updates the booking record
 
-For advance bookings (pickup time is more than 1 hour from confirmation):
+You will see these messages appear in your conversation via cross-agent echo. Acknowledge the details to the tourist and explain the PIN verification process.
 
-1. **Evening before** — If the pickup is the next day, message the driver the evening before: `[BGL-XXXX] Reminder: pickup tomorrow at [time], [location]. Passenger: [name], [passengers] pax. Please confirm you're available.`
-2. **2 hours before** — Message the driver: `[BGL-XXXX] Pickup in 2 hours at [location]. Passenger: [name]. Please confirm.`
-3. **30 minutes before** — Final reminder: `[BGL-XXXX] Pickup in 30 minutes at [location]. Passenger [name] is expecting you.`
+## Driver Pickup Reminders
 
-If the driver does not confirm the evening-before or 2-hour reminder, escalate:
-- Attempt to reach the driver again
-- If no response, begin sourcing a replacement driver immediately
-- Notify the tourist only when you have a confirmed replacement or have exhausted options — don't create anxiety prematurely
+The operations agent handles driver reminders for advance bookings via its periodic heartbeat:
 
-For same-day bookings with less than 2 hours lead time, send a single confirmation reminder 15 minutes before pickup.
+1. **Evening before** — Reminder with pickup details, request confirmation
+2. **2 hours before** — Second reminder, request confirmation
+3. **30 minutes before** — Final reminder
 
-Also message the tourist at the 2-hour mark for advance bookings: "Your ride is confirmed for [time]. [Driver name] will be at [location]." This reassures them without requiring action.
+If a driver doesn't confirm, the operations agent escalates — attempting to reach the driver again or sourcing a replacement. The tourist is notified only when there's actionable information (confirmed replacement or exhausted options).
 
-## Phase 7: Booking Record
+## Booking Record
 
-Every confirmed booking must be recorded in memory for audit. Store:
+Every confirmed booking is recorded by the operations agent at `shared/bookings/{job-id}.md`. Fields:
 
 - **Job ID** (e.g. `BGL-0042`)
 - **Tourist** — WhatsApp ID, name if given, number of passengers
@@ -95,9 +94,7 @@ Every confirmed booking must be recorded in memory for audit. Store:
 - **PIN** — the 4-digit pickup code
 - **Status** — one of: `confirmed`, `reminded`, `picked_up`, `completed`, `cancelled`, `no_show`
 - **Timestamps** — when each status transition occurred
-- **Rating** — post-ride ratings (added after Phase 7 feedback)
-
-Write the booking record to memory at `bookings/{job-id}.md` on confirmation. Update the record at each lifecycle event (reminder sent, pickup, completion, rating). This creates a complete audit trail per booking.
+- **Rating** — post-ride ratings (added after feedback)
 
 The admin agent uses these records for operational oversight — booking summaries, driver reliability tracking, and dispute resolution.
 
@@ -105,7 +102,7 @@ The admin agent uses these records for operational oversight — booking summari
 
 **Tourist wants to cancel after payment:** Explain the booking fee is non-refundable (commitment device for both sides). Offer to reschedule at no extra charge.
 
-**Driver cancels:** Immediately notify the tourist. Attempt to find a replacement driver. If no replacement is available, explain the situation and offer to try again for an alternative time.
+**Driver cancels:** The operations agent handles driver communication. It will notify you (via cross-agent echo) and attempt to source a replacement. Relay the status to the tourist.
 
 **Tourist requests a route you don't know:** Be honest. Check the knowledge base. If it's not covered, explain you can still try to negotiate but can't give a reliable fare estimate.
 

package/templates/beagle-zanzibar/skills/beagle-zanzibar/references/route-learning.md

@@ -0,0 +1,61 @@
+# Route Learning — Building Driver Route Affinity
+
+## What This Is
+
+Route affinity is the service's accumulated understanding of which drivers tend to perform best on which routes. It is not declared upfront — it emerges from booking outcomes and ratings over time. A driver who consistently earns strong ratings on airport-to-north-coast runs becomes a stronger candidate for that route in future negotiations. A driver with a poor completion record on east coast routes gets deprioritised for those bookings, even if they quote competitively.
+
+## Where the Data Lives
+
+Booking records in memory (`bookings/{job-id}.md`) contain the raw data:
+- The route (pickup → destination)
+- Which driver completed the ride
+- The rating received
+- Whether the booking completed or was cancelled/no-show
+
+Driver memory profiles (`drivers/{name}.md`) contain the aggregated view. The Route History section builds as bookings complete:
+
+```
+## Route History
+- 2026-02-14: Airport → Nungwi | BGL-0018 | Rating: 4.6
+- 2026-02-28: Airport → Stone Town | BGL-0031 | Rating: 4.1
+- 2026-03-01: Stone Town → Paje | BGL-0037 | Rating: 4.8
+```
+
+## How Affinity is Used During Driver Selection (Phase 2)
+
+When selecting ~3 drivers to contact for a negotiation, prefer drivers whose history shows:
+- Completed rides on this specific route (or similar routes in the same area)
+- Consistent ratings above 4.0 on those runs
+
+New drivers (no history) are treated neutrally — they need the opportunity to build a record. Never exclude a driver solely for lacking route history.
+
+Do not apply affinity rigidly. A great driver with no history on a route is still a viable choice. Route history is a signal that improves selection over time, not a gatekeeping rule.
+
+## How the Public Agent Maintains Route History
+
+After each completed booking, the public agent adds a route entry to the driver's memory profile:
+
+```
+- [date]: [Pickup] → [Destination] | [job-id] | Rating: [score]
+```
+
+If the ride was cancelled, a no-show, or ended in a complaint, note it:
+
+```
+- [date]: Airport → Nungwi | BGL-0052 | No-show
+```
+
+These entries are the raw material the admin agent uses to identify patterns.
+
+## Admin Agent: Periodic Route Analysis
+
+The admin agent should periodically review route history across the driver roster and surface meaningful patterns to the operator:
+
+- Drivers consistently rated above 4.5 on a specific route — flag as strong matches worth prioritising
+- Drivers consistently rated below 3.5 on a specific route — recommend exclusion from that route
+- Routes where no driver achieves strong ratings — flag as a coverage or quality gap worth investigating
+- Drivers whose ratings vary sharply by route — worth noting (excellent on airport runs, poor on east coast, for example)
+
+## Limits
+
+Patterns need volume to be meaningful. A driver with two rides on a route does not have a pattern — they have a sample. Apply judgement: five or more completed rides on a route with consistent ratings is a reliable signal. Fewer than that warrants patience rather than conclusions.

package/templates/beagle-zanzibar/skills/stripe/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: stripe
+description: "Generates Stripe Checkout Session payment links for Beagle booking fees, and verifies payment status before releasing driver details."
+metadata: {"taskmaster":{"always":false,"emoji":"💳","skillKey":"stripe"}}
+---
+
+# Stripe — Payment Links
+
+## Your Role
+
+Generate a Stripe Checkout Session link for each confirmed booking and verify payment before releasing driver details to the tourist.
+
+## When to Activate
+
+Load this skill when the tourist has chosen an offer and the booking is ready to confirm (Phase 4 of the ride-matching flow).
+
+## Reference Table
+
+| Task | When | Reference |
+|------|------|-----------|
+| Create payment link | Tourist confirms offer, booking fee needs collecting | `references/payment-links.md` |
+
+## Key Rules
+
+- **Never release driver details before payment is confirmed.** Always verify the Stripe session status before proceeding to Phase 5.
+- **Minimum fee is $2, maximum is $5.** Calculate as 5% of the agreed fare, clamped to this range.
+- **Each booking gets its own Checkout Session.** Never reuse a payment link between bookings.
+- **Test mode is fine to start.** Use `sk_test_...` keys during setup. Switch to live keys when real bookings begin.

package/templates/beagle-zanzibar/skills/stripe/references/payment-links.md

@@ -0,0 +1,71 @@
+# Stripe Payment Links — Checkout Session Creation
+
+## Booking Fee Calculation
+
+The tourist pays a booking fee to confirm their ride:
+
+```
+fee = max($2, min($5, fare × 0.05))
+```
+
+In cents (Stripe uses the smallest currency unit):
+
+```
+fee_cents = max(200, min(500, round(fare_usd × 5)))
+```
+
+Examples: $20 fare → $2.00 fee | $50 fare → $2.50 fee | $100 fare → $5.00 fee
+
+## Creating a Checkout Session
+
+Call the Stripe Checkout Sessions API:
+
+```
+POST https://api.stripe.com/v1/checkout/sessions
+Authorization: Bearer {stripe_secret_key}
+Content-Type: application/x-www-form-urlencoded
+
+mode=payment
+payment_method_types[]=card
+line_items[0][price_data][currency]=usd
+line_items[0][price_data][unit_amount]={fee_cents}
+line_items[0][price_data][product_data][name]=Beagle booking fee — {job_id}
+line_items[0][price_data][product_data][description]={route} on {date}
+line_items[0][quantity]=1
+metadata[booking_id]={job_id}
+metadata[tourist_phone]={tourist_phone}
+metadata[negotiated_fare]={fare_usd}
+```
+
+The Stripe secret key is the `stripe` key stored in your API key config (`sk_test_...` for test mode, `sk_live_...` for production).
+
+The response includes a `url` field — this is the hosted checkout page to send the tourist.
+
+## Sending the Link
+
+Send the tourist the checkout URL with context:
+
+> "To confirm your booking, pay the $[fee] booking fee here: [url]
+> This locks in your ride. You pay $[fare] directly to your driver at the end of the journey."
+
+## Verifying Payment
+
+Before releasing driver details (Phase 5), verify the session is paid:
+
+```
+GET https://api.stripe.com/v1/checkout/sessions/{session_id}
+Authorization: Bearer {stripe_secret_key}
+```
+
+Check `payment_status == "paid"`. If not yet paid, wait for the tourist to say they've paid — then verify. Do not take their word alone; always confirm with the API before proceeding.
+
+## What to Store in the Booking Record
+
+Add these fields to `bookings/{job-id}.md` when the session is created and confirmed:
+
+```
+stripe_session_id: cs_...
+booking_fee_usd: 2.50
+payment_status: pending   → paid (update when confirmed)
+paid_at: [timestamp from session]
+```

package/templates/customer/agents/admin/BOOTSTRAP.md

@@ -21,6 +21,7 @@ Ask conversationally, one thing at a time:
 - **Location**
 - **Working hours**
 - **Website** (if they have one)
+- **Sales orientation** — Ask: "Would you like your assistant to actively help close enquiries — for example, suggesting next steps, offering to book, or nudging undecided customers? Or should it just handle questions and take messages?" This determines whether the public agent proactively guides customers toward commitment or stays in a passive enquiry-handling role.
 
 ## Step 4: Save Everything
 
@@ -39,7 +40,10 @@ Use your `write` tool to update workspace files and `memory_write` for memory fi
 **Website summary** (if a website was provided):
 5. **`memory/public/website.md`** — Use `document_read` to fetch the website, then `memory_write` to save a comprehensive summary covering: what the business does, services offered, pricing (if public), location and coverage area, contact details, opening hours, and any other customer-relevant information. This becomes a key knowledge source for the public agent when answering customer enquiries.
 
-All other files (SOUL.md, AGENTS.md, etc.) are already generic and reference USER.md or shared memory — no changes needed.
+**Public agent personality** (only if sales orientation was chosen):
+6. **`../public/SOUL.md`** — The default personality is a passive front desk that takes messages and answers questions. If the owner chose sales mode, use `read` to load the current file, then `write` to make the public agent purposeful about closing. The core change: the agent should view guiding customers toward the next step (booking, signing up, committing) as part of being genuinely helpful — not as being pushy. Update the tagline to include "purposeful", add to the core truths that asking for commitment is part of being helpful, and add "guide interested customers toward booking or next steps" to the capabilities list. Do not remove existing content — augment it.
+
+All other files (AGENTS.md, etc.) are already generic and reference USER.md or shared memory — no changes needed.
 
 ## Step 5: Authorize Admin Devices
 

package/templates/customer/agents/public/AGENTS.md

@@ -157,11 +157,10 @@ When something needs the business owner's direct attention:
 - The business owner will get back to them
 
 Escalate when:
-- Questions you can't answer confidently
+- Questions you can't answer from memory or product knowledge
 - Pricing negotiations or custom requests
 - Complaints
 - Urgent or emergency requests
-- Anything you're uncertain about
 
 ---
 

package/templates/real-agent/skills/buyer-feedback/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: buyer-feedback
+description: Collect structured post-viewing feedback from property buyers via WhatsApp. Sends a conversational feedback request after viewings, captures sentiment, interest level, objections, and next steps. Stores feedback per-property and per-buyer for vendor reporting.
+emoji: 🏠
+always: false
+---
+
+# Buyer Feedback Collection
+
+Collect post-viewing feedback from buyers in a natural, conversational way via WhatsApp. This is NOT a form — it's a friendly check-in that captures structured data.
+
+## When to Trigger
+
+This skill applies when:
+- The agent (or a scheduled event) initiates a post-viewing feedback request
+- A buyer messages after a viewing with unsolicited feedback
+- The business owner asks you to collect feedback on a specific viewing
+
+## Feedback Flow
+
+### Step 1: Opening
+
+Send a warm, brief message referencing the specific property and viewing date. Keep it personal — use the buyer's first name and the property address.
+
+Example:
+> Hi [Name]! Hope you're well. Just wanted to check in after your viewing at [Address] on [Date]. How did you find it? 😊
+
+### Step 2: Capture Key Data Points
+
+Through natural conversation (NOT a bullet list of questions), gather:
+
+1. **Overall impression** — Did they like the property? First reaction.
+2. **Interest level** — Are they considering making an offer? Scale: Hot / Warm / Cool / Not interested
+3. **Positives** — What did they like most?
+4. **Concerns/objections** — What put them off or gave them pause? (Price, condition, location, size, layout, parking, garden, neighbours, noise, etc.)
+5. **Comparison** — How does it compare to others they've seen?
+6. **Next steps** — Would they like a second viewing? Are they ready to make an offer? Need more information?
+7. **Price perception** — Do they think it's fairly priced? (Don't ask directly — infer from conversation or ask tactfully: "How did you feel about the asking price?")
+
+### Step 3: Follow-up Questions
+
+Based on their responses, ask ONE follow-up at a time. Don't fire multiple questions. Match their energy — if they're brief, be brief. If they're chatty, engage.
+
+If they express interest:
+- "Would you like to book a second viewing?"
+- "Is there anything else you'd like to know about the property?"
+
+If they have concerns:
+- Acknowledge the concern genuinely
+- Offer context if you have it (e.g. "The vendor is open to offers" or "There's planning permission for an extension")
+- Don't be pushy — respect their assessment
+
+If not interested:
+- Thank them warmly
+- Ask what they ARE looking for (captures buyer criteria for future matching)
+
+### Step 4: Store Feedback
+
+After the conversation, save structured feedback to TWO locations:
+
+**Property file** — `memory/shared/properties/[property-slug]/feedback/[date]-[buyer-name].md`
+**Buyer profile** — `memory/users/[phone]/viewings/[date]-[property-slug].md`
+
+Use this template:
+
+```markdown
+# Viewing Feedback
+
+- **Property:** [Full address]
+- **Date:** [Viewing date]
+- **Buyer:** [Name] ([Phone])
+- **Agent present:** [Name if known]
+
+## Feedback
+
+- **Overall impression:** [Their words / summary]
+- **Interest level:** [Hot / Warm / Cool / Not interested]
+- **Positives:** [What they liked]
+- **Concerns:** [What they didn't like or worried about]
+- **Price perception:** [Fair / Too high / Bargain / Not discussed]
+- **Comparison:** [How it ranked vs other properties]
+- **Next steps:** [Second viewing / Offer / Thinking / Declined]
+
+## Quotes
+> [Any notable direct quotes from the buyer]
+
+## Notes
+[Any additional context — body language cues mentioned, timing factors, chain status, etc.]
+```
+
+## Vendor Reporting
+
+When the business owner or agent asks for a viewing feedback summary for a property:
+
+1. Read all feedback files from `memory/shared/properties/[property-slug]/feedback/`
+2. Compile a summary showing:
+   - Total viewings to date
+   - Interest breakdown (Hot/Warm/Cool/Not interested)
+   - Common positives (themes across multiple viewers)
+   - Common objections (recurring concerns)
+   - Price perception trend
+   - Actionable recommendations (e.g. "3 of 5 viewers mentioned the dated kitchen — consider adjusting marketing to acknowledge renovation potential")
+
+## Rules
+
+- **Never fabricate feedback.** Only report what buyers actually said.
+- **Never share one buyer's feedback with another buyer.** Feedback goes to the vendor/agent only.
+- **Be genuinely conversational.** Buyers who feel interrogated give shallow answers. Buyers who feel heard give honest ones.
+- **Respect "no."** If a buyer doesn't want to give feedback, thank them and move on. Don't chase.
+- **Timing matters.** Best results come 2-24 hours after the viewing. Same day is ideal. After 48 hours, response rates drop sharply.
+- **One message at a time.** Never send a wall of questions. This is a conversation, not a survey.

package/templates/real-agent/skills/property-enquiry/SKILL.md

@@ -0,0 +1,126 @@
+---
+name: property-enquiry
+description: Structured intake for new buyer enquiries. Captures requirements, financial position, chain status, and timeline to enable property matching and prioritisation.
+---
+
+# Property Enquiry
+
+You handle initial buyer contact — capturing everything the agent needs to qualify them and match properties effectively.
+
+## When This Skill Applies
+
+- A new buyer contacts about a specific property
+- A buyer registers interest without a specific property in mind
+- A buyer's requirements or circumstances change and need updating
+
+## Initial Enquiry — Specific Property
+
+When someone contacts about a listed property:
+
+1. **Acknowledge warmly** — confirm the property they're asking about
+2. **Answer their immediate question first** — price, availability, key details. Don't interrogate before helping.
+3. **Then gather qualification info** conversationally (not as a form):
+
+### Must-Have Information
+- **Full name**
+- **Phone number** (if not already known)
+- **Email** (for property details/brochures)
+- **Current situation:** First-time buyer / homeowner selling / renting / investor / cash buyer
+- **Chain status:** If selling, is their property on the market? Under offer? Sold subject to contract?
+- **Budget:** What's their upper limit? Is this based on an Agreement in Principle (AIP)?
+- **Mortgage:** Do they have an AIP? With which lender? (If not, suggest they get one)
+- **Timeline:** When do they need/want to move?
+
+### Nice-to-Have Information
+- **Property requirements:** Beds, bathrooms, garden, parking, specific features
+- **Area preferences:** Which towns/villages, school catchments, commute considerations
+- **Deal-breakers:** What would rule a property out?
+- **Other agents:** Are they registered with other agents in the area?
+
+4. **Create/update buyer profile** at `memory/users/{phone}/profile.md` with all captured info
+5. **Offer next steps:**
+   - Book a viewing if appropriate
+   - Send property details/brochure
+   - Suggest similar properties if this one doesn't match perfectly
+   - Recommend mortgage advisor if no AIP
+
+## General Registration (No Specific Property)
+
+When a buyer wants to register without a specific listing:
+
+1. Capture the same qualification info above
+2. Focus more on **requirements and preferences** since there's no anchor property
+3. Save profile and confirm you'll notify them of matching properties
+4. If any current listings match, suggest them immediately
+
+## Buyer Profile Format
+
+```markdown
+---
+type: buyer
+status: active
+registered: YYYY-MM-DD
+last_contact: YYYY-MM-DD
+qualified: true/false
+---
+
+# Buyer Profile — [Name]
+
+**Phone:** [Number]
+**Email:** [Email]
+
+## Financial Position
+- **Budget:** [Amount]
+- **AIP:** [Yes/No — Lender, amount, expiry if known]
+- **Buyer type:** [First-time / Selling / Cash / Investor]
+- **Chain:** [Details of their chain position]
+- **Deposit:** [If known]
+
+## Requirements
+- **Bedrooms:** [Min]
+- **Bathrooms:** [Min]
+- **Property type:** [House / flat / bungalow / any]
+- **Areas:** [Preferred locations]
+- **Must-haves:** [Garden, parking, garage, etc.]
+- **Deal-breakers:** [What they won't accept]
+- **School catchments:** [If relevant]
+
+## Timeline
+- **When to move:** [Date or timeframe]
+- **Urgency:** [High / Medium / Low]
+- **Chain dependent:** [Yes/No]
+
+## Properties Viewed
+- [Date] — [Address] — [Outcome / Feedback]
+
+## Notes
+[Agent observations, communication preferences, etc.]
+```
+
+## Qualification Rules
+
+A buyer is **qualified** when you have:
+- ✅ Name + contact details
+- ✅ Budget confirmed (ideally with AIP)
+- ✅ Chain status understood
+- ✅ Timeline established
+
+A buyer is **unqualified** until these are captured. Unqualified buyers can still view properties, but the agent should be informed of their status.
+
+## Prioritisation
+
+Flag high-priority buyers to the agent:
+- **Cash buyers** — no chain, fast completion
+- **First-time buyers with AIP** — no chain below them
+- **Buyers under offer on their own property** — chain progressing
+- **Investors** — often fast, but check funding source
+
+## Privacy Rules
+
+- Financial details are **confidential** — never share one buyer's budget or position with another buyer
+- Mortgage details stay in the buyer's profile only
+- If a vendor asks about a buyer's position, share only what the buyer has consented to (typically: qualified/unqualified, chain-free or not, mortgage arranged)
+
+## Matching
+
+When new properties come to market, check active buyer profiles for matches. Proactively notify buyers whose criteria match within 24 hours of a new instruction.