Guided-flow onboarding playbook

How to onboard a merchant/tenant onto a Guided flow (ADR-0168), framed by the four-stage Anatomy. Domain terms (Persona, Guided flow, Draft, Card, Source, Pack, Completed flow) are defined in CONTEXT.md. Packaging/gating in ADR-0168. Phase-1 templates in ADR-0167.

Status: Draft (design)
Date: 2026-07-04

The Anatomy — one loop, every vertical

01 Understand → 02 Curate → 03 Refine → 04 Complete
   elicit slots   grounded     reshape     deliver Draft →
                  Draft                    capture / handoff

Invariants that hold on every turn (do not weaken per-merchant): grounded & cited (facts only from the tenant’s Sources ∪ subscribed Packs — never the model’s own knowledge), tenant-isolated, Draft server-side (client never replays it — ADR-0017), PDPA-safe (hashed query logs, per-tenant retention), Thai-first, any channel.

What to prepare per stage

Stage	What the tenant/onboarder prepares	Puccha primitive
Understand	The 3–5 slots that actually change the answer (dates, size, budget, use-case). Encoded in the `Persona` systemPrompt.	`Persona` (Retail/HR/… template)
Curate	The knowledge to ground the `Draft`: unstructured policy/FAQ as Sources; structured catalogue/price/stock as a Data Table.	`Source` ingest + `queryStructuredData`
Refine	Nothing extra — refinement reshapes the same `Draft` across turns from the same knowledge.	server-side `Draft` state
Complete	The terminal action + who confirms it (capture contact, handoff, generate doc). Defines the Completed flow billable event = `Draft` first delivered.	`captureContact` / `escalateToHuman`

The general kit (any merchant): ① a Data Table for anything numeric/queryable (price, stock, specs) so the agent never guesses figures; ② Sources for policy/terms/FAQ; ③ a Persona from the closest vertical template with the right toolsEnabled; ④ a Channel binding (web widget and/or LINE/etc.); ⑤ a Completion definition (which Draft, who confirms).

Worked example — WinterClothingShop (rentals)

Merchant (winterclothingshop.com, local project WinterClothingShop/winter-website, Next.js + Payload CMS): a Thai winter-wear rental + retail shop (North Face, Columbia, Patagonia…). Rents snow boots ฿1,500–1,800; deposit refunded on return; nationwide delivery, free >฿1,000; Thai-primary. Support runs on LINE @winterclothing1 via a floating contact button — no chat widget, no chatbot today.

The finding that shapes the design: on their site “rental” is copy, not a data model. Products.ts has a single free-text rentalPrice ("1,500 บาท / 10วัน"), no deposit, no per-day price, no rental dates, no date-based availability. All real rental work (dates, deposit, quote) is a manual LINE back-and-forth — described by the /rental page’s steps (step 2 = “แจ้งวันเดินทาง”). That conversation is the Guided flow.

Anatomy mapped to this merchant

Move	For WinterClothingShop	Output
Understand	trip/occasion, rental dates (pickup→return), who (men/women/kids), item, size, delivery vs. pickup	elicited slots
Curate	query the rental catalogue Data Table for matching in-stock items + size; compute period price	Draft = rental shortlist: item + size + price + deposit
Refine	“warmer / cheaper / different size / add gloves / change dates”	reshaped Draft
Complete	capture contact → Reservation Draft → handoff to staff on LINE to confirm dates + deposit	Completed flow

The onboarding kit

Data Table — the rental catalogue (highest-leverage prep, because rentalPrice is free text). Normalize into structured columns and add the two fields their schema lacks:

products_rental — Data Table
  code · name · brand · category
  sizes_in_stock · deposit* · price_amount* · period_days* · stock
  (* net-new — not in Products.ts today)

Sources — upload existing copy as documents: rental terms + 4-step how-to (/rental), pricing/deposit FAQ (“฿600–3,000 / 10 วัน”, counted pickup→return), refund-on-return policy, sizing guide (US↔EU↔TH + warmth/temperature ratings), delivery/shipping.
Persona — “ผู้ช่วยเช่า” from the Retail/E-commerce template; Thai-first, warm; toolsEnabled: searchKnowledgeBase + queryStructuredData + captureContact + escalateToHuman. Starter questions: “เช่ารองเท้าไปเที่ยวญี่ปุ่น 5 วัน” / “มัดจำเท่าไร” / “ไซซ์ 7US มีรุ่นไหนบ้าง”.
Channel — LINE first. Bind the Persona to @winterclothing1 (their existing support line) via Puccha’s LINE channel. The web widget on the site is a free second surface.
Completion = Reservation Draft delivered → handoff to confirm dates + deposit (the billable Completed flow, ADR-0168).

The honesty rule (the design’s sharp edge)

Because there is no date-based inventory, the agent must not claim “available on your dates” — that would fabricate a fact and violate the grounding invariant. So the flow builds the Reservation Draft and hands off to staff to confirm the slot + deposit — which is exactly their current LINE process, only pre-filled and instant. Presenting the honest “subject to confirmation” is on-brand for a compliance-grounded product, not a gap.

Upgrade path to instant confirmation (not needed for v1): a merchant-maintained date-availability Data Table, or a Phase-2 external inventory API (the deferred httpTool).

Reference flow (LINE, Thai)

คุณ:  เช่ารองเท้าสโนว์ไปเที่ยวญี่ปุ่น 5 วัน ไซซ์ 7US
บอท:  ได้เลยค่ะ ❄️ ขอทราบวันรับ–คืน และรับที่ร้านหรือให้จัดส่งดีคะ?
คุณ:  20–24 นี้ ส่งกรุงเทพ
บอท:  ไซซ์ 7US มีรุ่นที่เหมาะกับหิมะค่ะ ร่างใบจองให้แล้วนะคะ 👇
      ┌ ใบจองเช่า (ร่าง)
      │ รุ่น       Columbia Snow Boot 7US
      │ ช่วงเช่า   20–24 ก.ค. · 5 วัน
      │ ค่าเช่า    ฿1,500 / รอบ (≤10 วัน)
      │ มัดจำ      ฿2,000 · คืนเมื่อส่งคืน
      │ จัดส่ง     กรุงเทพฯ · ฟรี
      │ * คิวว่างช่วงวันที่เลือก เจ้าหน้าที่ยืนยันอีกครั้ง
      └ อ้างอิง: แคตตาล็อกเช่า · เงื่อนไขการเช่า
      → ส่งต่อเจ้าหน้าที่ · ยืนยันคิว + รับมัดจำ   [Completed flow]

The Draft uses the merchant’s real per-period pricing (฿1,500/รอบ) rather than inventing per-day proration — grounding in their actual model, not a guess.

Reuse

This playbook is vertical-agnostic: swap the Data Table + Sources + Persona template and the same four-stage kit onboards a tourism concierge (itinerary Draft), a sales assistant (qualified-lead Draft), or an HR desk (leave-request Draft). WinterClothingShop is the first worked example; add others below as they are onboarded.