Sync from GitHub

JOURNEYS.md

@@ -0,0 +1,55 @@
+# 🧭 Customer Journeys
+
+Every answer must hand the person their **next action** — a link, an
+eligibility line, or a follow-up chip. If an answer names a service without a
+route in, that's a bug (see the route-in audit, June 2026).
+
+The design loop for each journey:
+
+> **question → intent → live tool → answer → next action → follow-up chips**
+
+## The journeys
+
+| # | Who & what they ask | Intent | Tool | The answer must hand them |
+|---|---|---|---|---|
+| 1 | "Do you have Harry Potter audiobooks?" | Borrow a specific title | `search_catalogue` | Matches with format/year + detail links · **To borrow:** join-online / digital-membership links · full-results link |
+| 2 | "Any good new crime novels?" | Discover something to read | `whats_new` | Newest titles · the same **To borrow** join link · see-more link |
+| 3 | "Is Malvern library open now?" | Visit a branch today | `find_library` | 🟢/🔴 open-now + today's hours · address · facilities · **Libraries Unlocked hours + how to get access** · branch page |
+| 4 | "A late-opening library with a café" | Pick the *right* branch | `graph_search` | Matching branches as **links with addresses** · "ask me 'is it open now?'" hint |
+| 5 | "When does the van visit Abberley?" | Catch the mobile library | `mobile_library` | Stop times · "join on the van" · enquiry email · timetable link |
+| 6 | "What's on this week?" | Take the kids somewhere | `library_events` | Events as links with dates/places · "most are free, just turn up" |
+| 7 | "Can I read newspapers for free?" | Read/research from home | `online_hub` | Resource name **linked to its council page** · what you need · **app-store + web links** (PressReader, BorrowBox) · access steps |
+| 8 | "How do I print from my phone?" | Print without a printer | `printing_help` | Steps with **join link** + **device-guide page link** · prices · the PaperCut kiosk caveat |
+| 9 | "What do I need to sign up?" | Join (right tier, least effort) | `membership_help` | Each tier **linked to its own page** — digital membership links straight to instant sign-up |
+| 10 | "Can I get in after work?" | Use the library out of hours | `libraries_unlocked` | Hours · the 11 branches · induction requirement · **join-online link for non-members** |
+| 11 | Greeting / off-topic | Find out what this thing does | none (`HELP`) | Capability list + four starter chips |
+
+## Journey-chaining (the chips)
+
+Answers end with up to three **suggestion chips** (`NUDGES` in `app.py`) that
+chain journeys together, EAST-style — e.g. a branch-hours answer (3) offers
+"Tell me about Libraries Unlocked" (10); a catalogue answer (1) offers "Is it
+on BorrowBox?" (7). The chip's answer must contain the links the nudge text
+alludes to — the nudge itself stays short.
+
+## Cross-journey guarantees
+
+- **Provenance:** every answer footer shows when it was checked, which tool
+  ran, and a source link.
+- **Value receipt:** borrowing/online/printing answers show the £ saved
+  (`value_receipt`).
+- **Tone:** lead with what the person *can* do — never open with a bare "no"
+  (`SYNTH_SYSTEM`). The print-from-home question is the canonical example:
+  "send it from your phone, collect at any branch" beats "no, but…".
+- **Degradation:** if the live source is down, say so plainly; with no
+  `HF_TOKEN` the rendered data stands alone, so every link above lives in the
+  *data/renderers* (`library_sources.py`, the `render_*` functions) — never
+  only in LLM phrasing.
+
+## Maintaining this
+
+When adding or changing an answer, walk the loop: *what will the person do
+next?* If the answer mentions a service, membership step, app or page — link
+it, in the renderer or curated data, and check the chips chain somewhere
+useful. Then re-run the battery in the PR #5 audit (a question per row above)
+against `respond()`.

README.md

@@ -36,6 +36,9 @@ back from the council's own systems, and explains it:
 Every reply carries a **“checked live just now” footer** with the tool used and a
 link back to the official page.
 
+Each answer is designed around a customer journey — what the person is trying
+to do and the next action the reply must hand them. See **[JOURNEYS.md](JOURNEYS.md)**.
+
 ## The honest small-model fit
 
 The model never invents library facts. The intelligence lives in the **live

app.py

@@ -195,7 +195,7 @@ def render_catalogue(r):
         link = f" — [details]({it['detail_url']})" if it["detail_url"] else ""
         out.append(f"- {it['icon']} **{it['title']}** — {meta}{tag}{link}")
     out.append(f"\n✅ **To borrow:** {ls.ELIGIBILITY['borrow_physical']} "
-               f"eBooks/audio need free digital membership.")
+               f"eBooks/audio need free [digital membership]({ls.JOIN_URL}).")
     out.append(f"🔎 [Full results]({r['search_url']})")
     return "\n".join(out)
 
@@ -207,7 +207,8 @@ def render_whats_new(r):
     for it in r["items"]:
         meta = " · ".join(b for b in (it["author"], it["year"]) if b)
         out.append(f"- {it['icon']} **{it['title']}** — {meta}")
-    out.append(f"\n🔎 [See more]({r['search_url']})")
+    out.append(f"\n✅ **To borrow:** {ls.ELIGIBILITY['borrow_physical']}")
+    out.append(f"🔎 [See more]({r['search_url']})")
     return "\n".join(out)
 
 
@@ -225,7 +226,9 @@ def render_find_library(r):
            f"{r['address']}\n",
            f"**Today ({r['today']}):** {r['today_staffed'] or 'see below'}"]
     if r.get("unlocked_today"):
-        out.append(f"**Libraries Unlocked self-service:** {r['unlocked_today']}")
+        out.append(f"**Libraries Unlocked self-service:** {r['unlocked_today']} — "
+                   f"{ls.ELIGIBILITY['unlocked']} "
+                   f"[How to get access]({ls.UNLOCKED_URL})")
     if r.get("facilities"):
         out.append(f"\n**Facilities:** {', '.join(r['facilities'])}")
     out.append(f"\n✅ {ls.ELIGIBILITY['visit']}")
@@ -261,7 +264,8 @@ def render_events(r):
 def render_online_hub(r):
     out = ["💻 **Free online — with your library card:**\n"]
     for it in r["items"][:5]:
-        out.append(f"**{it['name']}** — {it['summary']}")
+        name = f"[{it['name']}]({it['url']})" if it.get("url") else it["name"]
+        out.append(f"**{name}** — {it['summary']}")
         if it.get("what_you_need"):
             out.append(f"  - ✅ **What you need:** {it['what_you_need']}")
         if it.get("access"):
@@ -278,7 +282,8 @@ def render_online_hub(r):
 def render_unlocked(r):
     out = ["🔓 **Libraries Unlocked** — use the library 8am–8pm, Mon–Sat, even "
            "when it's unstaffed.",
-           f"\n✅ **What you need:** {r['what_you_need']}"]
+           f"\n✅ **What you need:** {r['what_you_need']} "
+           f"Not a member yet? [Join online]({ls.JOIN_URL}) first."]
     if r.get("unlocks"):
         out.append(f"\n{r['unlocks']}")
     else:
@@ -294,7 +299,9 @@ def render_unlocked(r):
 def render_membership(r):
     out = ["🪪 **What you need to sign up:**\n"]
     for tier in r["tiers"]:
-        out.append(f"**{tier['tier']}** — {tier['what_you_need']}")
+        name = (f"[{tier['tier']}]({tier['url']})" if tier.get("url")
+                else tier["tier"])
+        out.append(f"**{name}** — {tier['what_you_need']}")
         out.append(f"  - _Unlocks:_ {tier['unlocks']}\n")
     if r.get("need"):
         out.append(f"➡️ For your question: **{r['need']}**")
@@ -329,7 +336,11 @@ def render_graph(r):
         out = [f"🧭 Libraries matching **{crit}**:\n"]
         for b in r["branches"]:
             lu = " · open to 8pm" if b["libraries_unlocked"] else ""
-            out.append(f"- **{b['name']}**{lu} — {', '.join(b['facilities'])}")
+            name = f"[{b['name']}]({b['url']})" if b.get("url") else b["name"]
+            addr = f" — {b['address']}" if b.get("address") else ""
+            out.append(f"- **{name}**{lu}{addr} — {', '.join(b['facilities'])}")
+        out.append("\n💬 Ask me _\"is it open now?\"_ about any of these for "
+                   "live hours.")
         return "\n".join(out)
     if r["kind"] == "entity":
         if not r["entities"]:

library_sources.py

@@ -38,6 +38,8 @@ CATALOGUE_SEARCH = (
 MOBILE_INDEX = f"{GOV}/council-services/libraries/your-library-membership/mobile-library"
 EVENTS_URL = f"{GOV}/council-services/libraries/library-events-and-activities"
 PRINTING_URL = f"{GOV}/council-services/libraries/printing-and-photocopying-services"
+UNLOCKED_URL = f"{GOV}/council-services/libraries/libraries-unlocked"
+JOIN_URL = f"{GOV}/council-services/libraries/your-library-membership/join-library"
 ONLINE_HUB = f"{GOV}/council-services/libraries/online-library-hub"
 
 UA = (
@@ -331,11 +333,12 @@ PRINT_YOUR_WAY = {
     ),
     "device_requirements": "Android 12+, iOS 16+, macOS 12 (Monterey)+, or Windows 11.",
     "steps": [
-        "Be a full library member (free to join with a library card).",
+        f"Be a full library member — free, [join online]({JOIN_URL}) or in any library.",
         "Top up your PaperCut print account at a self-service kiosk in any "
         "Worcestershire library (some kiosks are cash-only, so check first).",
         "One-time setup: download and follow the Print Your Way guide for your "
-        "device (Android / iOS / macOS / Windows).",
+        f"device — Android, iOS, macOS and Windows guides are on the "
+        f"[printing page]({PRINTING_URL}).",
         "Open your document, choose the mono or colour print queue, set your "
         "options and send — authenticate with your library number and PIN.",
         "Release the job at any public printer in any Worcestershire library "
@@ -379,8 +382,10 @@ def kb() -> dict:
 
 # "What you need to sign up" — the eligibility that varies per service.
 ELIGIBILITY = {
-    "borrow_physical": "Free **full membership** (join online + collect, or in any library).",
-    "borrow_digital": "Free **digital membership** — instant, just a Worcestershire postcode.",
+    "borrow_physical": f"Free **full membership** ([join online]({JOIN_URL}) + collect, "
+                       "or in any library).",
+    "borrow_digital": f"Free **digital membership** — instant, just a Worcestershire "
+                      f"postcode ([sign up]({JOIN_URL})).",
     "printing": "Full membership + top up a PaperCut account at a library kiosk.",
     "mobile": "Free full membership — you can join on the van.",
     "unlocked": "Full member, aged 15+, after a short one-off staff induction.",
@@ -471,7 +476,7 @@ def libraries_unlocked(branch: str | None = None) -> dict:
            "hours": "8:00am to 8:00pm, Monday to Saturday",
            "what_you_need": tier.get("what_you_need", ELIGIBILITY["unlocked"]),
            "unlocks": tier.get("unlocks", ""),
-           "page_url": tier.get("url", f"{GOV}/council-services/libraries/libraries-unlocked"),
+           "page_url": tier.get("url", UNLOCKED_URL),
            "checked": _now()}
     if branch:
         b = branch.strip().lower()
@@ -490,7 +495,9 @@ CURATED_HUB = {
         "what_you_need": "Worcestershire library card number + PIN (free full membership, residents). No separate PressReader account needed.",
         "at_home": True,
         "access": [
-            "Get the PressReader app (or use pressreader.com).",
+            "Get the PressReader app — [iPhone/iPad](https://apps.apple.com/app/pressreader/id313904711) "
+            "or [Android](https://play.google.com/store/apps/details?id=com.newspaperdirect.pressreader.android) — "
+            "or read in your browser at [pressreader.com](https://www.pressreader.com).",
             "Tap 'Libraries & Groups' and search/select 'Worcestershire'.",
             "Sign in with your library card number + PIN.",
             "At home you get a 30-day pass (re-confirm monthly); on library Wi-Fi it's 7 days.",
@@ -504,7 +511,8 @@ CURATED_HUB = {
         "what_you_need": "Library card number + PIN; choose 'Worcestershire' in the app.",
         "at_home": True,
         "access": [
-            "Download the BorrowBox app.",
+            "Download the BorrowBox app — [iPhone/iPad](https://apps.apple.com/app/borrowbox-library/id562843562) "
+            "or [Android](https://play.google.com/store/apps/details?id=com.bolindadigital.BorrowBoxLibrary).",
             "Select 'Worcestershire' as your library service.",
             "Sign in with your card number + PIN.",
         ],
@@ -648,7 +656,7 @@ def online_hub(topic: str | None = None) -> dict:
 def membership_help(service: str | None = None) -> dict:
     """What you need to sign up — the cross-service membership matrix."""
     out = {"tiers": kb().get("membership_tiers", []),
-           "page_url": f"{GOV}/council-services/libraries/your-library-membership/join-library",
+           "page_url": JOIN_URL,
            "checked": _now()}
     if service:
         s = service.lower()