Add the Abri HubSpot ops guide, covering surveyor-change amendments

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

docs/abri-hubspot-ops-guide.md

@@ -0,0 +1,91 @@
+# Abri bookings: what your HubSpot changes do
+
+**Who this is for:** operations staff who work Abri deals in HubSpot — booking surveys,
+recording visit outcomes, updating deal fields.
+
+**The one-line version:** for deals on the Abri Stock Condition project, certain HubSpot
+field changes are picked up automatically and sent to Abri's scheduling system
+(OpenHousing). You never talk to OpenHousing directly — the deal fields are the controls.
+
+---
+
+## Which deals does this apply to?
+
+Only deals associated with the **Abri Stock Condition — Privately Funded** project.
+Changes to any other deal are ignored by this integration.
+
+## How fast does it happen?
+
+Changes are picked up automatically shortly after you save them in HubSpot — usually
+within a few minutes. Nothing fires while you are mid-edit; it's the saved change that
+counts.
+
+---
+
+## What your changes do in Abri's system
+
+| When you… | Abri's system… | How you know it worked |
+|---|---|---|
+| Set **Confirmed survey date** for the first time | Creates the survey booking (a "job") against the property, assigned to the surveyor on the deal | Abri's job number appears in **Client booking reference** on the deal |
+| Change **Confirmed survey date**, **Confirmed survey time** or **Third-party surveyor identifier** on a deal that already has a booking | Updates the existing appointment — new date/time and/or reassigns it to the new surveyor | The deal keeps the same Client booking reference |
+| Set **Expected commencement date** for the first time | Sends us the tenancy details for the property | Tenant contact records appear in HubSpot, linked to the deal |
+| Record a **3rd attempt** (Number of attempts reaches 3) **and** set **Outcome** to an unsuccessful value (see below) | Cancels the booking as abandoned | — (this only fires once per deal) |
+
+**Unsuccessful outcomes** that count towards abandonment — the wording must match exactly:
+
+- `no answer`
+- `cancelled / no show`
+- `tenant refusal`
+- `not viable`
+
+Any other outcome (or fewer than 3 attempts) does **not** cancel anything in Abri's
+system.
+
+## The fields, and why they matter
+
+| HubSpot deal field | What it feeds |
+|---|---|
+| **Confirmed survey date** | The appointment date sent to Abri |
+| **Confirmed survey time** | The appointment slot: `morning` → AM, `afternoon` → PM, a clock time like `09:30` → AM/PM by whether it's before midday, left blank → all day |
+| **Third-party surveyor identifier** | Which surveyor the booking is assigned to in Abri's system. **Required** — a booking or appointment change cannot be sent without it, and it must be one of Abri's valid surveyor codes. Changing it on a deal that already has a booking reassigns that booking to the new surveyor |
+| **Expected commencement date** | Setting it the first time triggers the tenant-details fetch |
+| **Number of attempts** + **Outcome** | Together they trigger abandonment (3+ attempts and an unsuccessful outcome) |
+| **Client booking reference** | Abri's job number, written back **by the system** after the booking is created |
+| **Deal name** | Used as the job description Abri's staff see |
+
+---
+
+## Things that will catch you out
+
+### Clearing the survey date does NOT cancel the booking
+
+If you delete or blank the confirmed survey date, the booking **still exists in Abri's
+system** and the surveyor is still expected. There is currently no way to cancel a
+booking from HubSpot other than the 3-attempts abandonment route. If a booking needs
+cancelling for any other reason, contact the tech team.
+
+### Don't edit Client booking reference
+
+It is written automatically with Abri's job number and is how the system finds the
+booking when you later change or abandon it. If you overwrite or clear it, appointment
+changes and abandonments will stop working for that deal.
+
+### The surveyor identifier must be a valid Abri code
+
+Free-typed or misspelt values will be rejected by Abri's system and the booking won't be
+made. The tech team holds the current list of valid surveyor codes from Abri — use a
+value from that list. (Longer term this field will be set automatically from the deal
+owner; until then it's set by hand.)
+
+### Outcome wording is exact
+
+Abandonment only recognises the four unsuccessful outcomes listed above, spelled exactly
+that way. A variation like "No Answer - left card" won't trigger it.
+
+### If the job number never appears
+
+The booking didn't go through — most often because the surveyor identifier was missing
+or invalid, or the deal isn't on the Abri project. Failures land with the tech team, not
+in HubSpot, so you won't see an error message. If **Client booking reference** is still
+empty well after you set the survey date, flag it to the tech team rather than re-editing
+fields.