Koofi

A consumer agent for one job: where should I go for coffee right now, and why?

People talk to it on a thin web chat, or later on WhatsApp. It is not an app-store app, not a marketing site, not a marketplace, and not a leads tool.

Owner: Amjad Puliyali. The real shop list still comes from him.

What it does

• Two landings, same chat: / is Arabic (وين ودّك تروح اليوم؟, Arabic chips, RTL). /en is English (Where do you want to go today?, English chips, LTR). Header switches with EN / عربي. Not a marketing site. Not both languages stacked in one bubble.
• بيننا is a utility card above an 8-chip 4×2 home grid (popular selected by default). Off-home chip URLs (roaster, specialty, study, late) stay live. Tapping a vibe chip still returns three pick cards. Soft Places stays parked. Typing the other language still flips the reply. WhatsApp has no chip UI; typing the same Arabic or English phrase maps the same way.
• They can also type a vibe or a neighborhood. A follow-up like أبعد عن العليا / away from Olaya gets another spoken line and a new three from the remaining catalog — not a general chat.
• District chat → top 3. Typing a live حي (EN / AR / aliases / common typos — حطين, Hittin, al narjis, النرجس, Olaya, العليا, …) returns exactly three in-district cafe cards ranked by the locked popularity index: 0.6 × log-norm(Maps reviewCount) + 0.4 × log-norm(IG followers). Ranking uses the baked popularityIndex (same index as Most Popular). Missing IG followers are 0 / bottom — the catalog has no durable igFollowers field; do not scrape Instagram. A chip links to /coffee-shops/{district-slug} (EN: /en/coffee-shops/{slug}) for the full district list. Soft Places vibe matching / “ثلاث الليلة” stays parked. Al Izdihar / الازدهار is catalog-live for Slant Specialty Coffee; the 21 Sep sheet row stays dictionary_only, same as Al Falah. Do not invent extra Izdihar shops.
• بيننا / Halfway. A utility card above the home chips (not a grid tile). One share URL wain.lol/h/{id} is the whole journey (/en/h/{id} is the English twin — same session, same pin state machine): Invite (one Ready location — موقعي / already-granted geo auto-Ready, Maps-share paste if denied — then اعزم خويك / Copy link), Waiting (ننتظر دبوس صاحبك. الثلاث تظهر هنا لحالها. / Waiting for your friend’s pin — three cafes will appear here.), Results (ثلاث قهاوي بينكم). After اعزم خويك the host replaces onto /h/{id} (EN host: /en/h/{id}) so host and guest share the session. Overlay GET: 1 pin → Waiting (host) or Invite (guest); 2+ pins or frozen shop_ids → the same three cards (refresh does not reshuffle). Waiting TTL is 45 minutes; completed sessions live 48 hours after results freeze. Expired shows clear copy plus Start a new Halfway — not a silent restart. Share results is the same /h/{id} (not /p/). No Save for later. Hero is pin–cup–pin (one cup). Lat/lng stay off the UI. Guest never copies the friend’s pin. Core API is locations: Location[] (N≥2); v1 UI is two people. Composer + أضف قهوة stay hidden while the flow is open. Soft Places stays parked.
• Koofi sends exactly three cafe picks when it can. It does not collapse to a single shop card when three shops exist. A short spoken line sits above the cards (xAI chat completions, grok-4.6). The share unit is still the cards: name, one-line why, and a Google Maps pin. For a real shop the Maps click is Amjad’s mapsShareUrl short link, not a reconstructed lat/lng search. People forward that pin to go. The /c/[id] card is optional and secondary. If XAI_API_KEY is missing or the model call fails, the spoken line falls back to today’s heading copy. Cards still send.
• Riyadh only. Neighborhoods: Hittin (حطين), Al Malqa (الملقا), An Nakheel (النخيل), Al Yasmin (الياسمين), Al Olaya (العليا), As Sulimaniyah (السليمانية), Al Wurud (الورود), Ar Rabwah (الربوة), Ar Rabi (الربيع), Al Masif (المصيف), Ar Rahmaniyyah (الرحمانية). Empty dictionary-only districts stay out of live discovery.
• Arabic in (Gulf / Saudi casual). Reply in the language they used. English if they switch. RTL-first.
• Reason over rating. Neighborhood and moment still choose the three shops — never sort or pick by stars. A real shop card may show Google’s rating, review count, and one short snippet via Places. If GOOGLE_PLACES_API_KEY is missing or the lookup fails, the rating row is hidden. Do not scrape Maps.
• كنت هنا / Been here cafe-card control is parked (SHOW_BEEN_HERE = false). Copy, localStorage mark, and picker “not as new” logic stay wired but the control is not user-facing. Flip the flag to show it again.
• Optional card at /c/[id]: name AR/EN, neighborhood, pin, vibe tags. Unclaimed shops stay a thin card. Verified shops unlock the richer Passport card (owner photos, brewing/note, owner-supplied hours only, thin offer, optional phone/IG, share, shared like, Maps CTA). Do not invent hours. Do not ask people to share a Koofi URL.
• وين؟ / wain? cafe-card CTA is parked (SHOW_INVITE_CTA = false) until share-tonight strategy is locked. Invite sheet, mint, and invite_* events stay wired but are not user-facing. Prefill stays وين؟ أنا بـ {name} / wain? I'm at {name} + /c/{id}?from=tonight. Spoken وين in Arabic copy elsewhere is fine. Listing share + Maps stay on the card.
• بطاقة الليلة / Tonight’s card is parked (SHOW_TONIGHT_CARD = false). Code and tonight_* events stay wired but are not user-facing.
• Each pick card has a small 44px letter mark from the shop name (IK, WO, …). A photoUrl is shown only if Amjad sets one. Do not scrape Maps photos.
• أضف قهوة / Add a shop sits under the composer, not in the chip row. Drop a Google Maps link. Koofi thanks them and stores a suggestion for Amjad — it does not go into catalog.json.

This is the beginning of the README. Read the rest at the original. Read the full README ↗