# Concierge Enrichment — Discovery Spike (2026-05-05)

Phase 1.5 re-scoped: agent generates **time-and-location-specific enrichment** (weather, local events during stay, seasonal hints) — *not* welcomes, check-in info, or anything the booking engine + lsa-pro already cover. Arrives T-1 or T-2 days as a complement, not a replacement.

## Recommended data-source stack (all free or near-free)

| Need | Source | Type | Status | Notes |
|---|---|---|---|---|
| Land weather (forecast 16d) | **Open-Meteo** `api.open-meteo.com/v1/forecast` | JSON, no key | ✅ tested today, perfect | daily + hourly, all variables |
| Marine forecast (waves, sea-temp) | **Open-Meteo Marine** | JSON, no key | ✅ tested today | useful for coastal properties |
| Land weather (PT-specific cross-check) | **IPMA** (Inst. Português do Mar e da Atmosfera) `api.ipma.pt/open-data/...` | JSON, no key | ✅ tested today | secondary source; useful for tide tables |
| Tide tables | IPMA `forecast/oceanography/...` | JSON, no key | ⏳ available, not yet wired | matters for coastal walks, boat trips |
| Algarve events (regional) | **amoteolhao.com**, **tomorrowalgarve.com** | scrape (HTML) | ✅ tested today, returned real data | weekly cache → SQLite |
| Algarve events (official) | **eventos.visitalgarve.pt** | JS-rendered page | ⚠️ needs Scrapling+playwright | already installed for Researcher-GAL |
| Local town events | Câmara Municipal sites (cm-tavira, cm-vrsa, cm-olhao…) | scrape | ⚠️ varies — VRSA worked, Tavira returned just header | per-town fallback |
| Concerts | Ticketmaster Discovery API | JSON, free 5000/day | ⏳ needs JG to register API key | covers Algarve venues partially |
| Static knowledge | hand-curated YAML | per-town weekly markets, beach-by-season, restaurant-opening calendar | ⏳ to build | one-time effort, never expires |

**No paid APIs needed** for v1. Stack stays at €0/mo.

## Two sample tip-sheets — generated from real 2026-05-08 arrivals

### Sample A — Gilles Poirier (PT) · Quinta da Capelinha #08 · 2 nights · 2026-05-08→10

> *Olá Gilles,*
>
> *Faltam 2 dias para a sua chegada à Quinta da Capelinha. Aqui ficam algumas dicas para a sua estadia:*
>
> **🌦️ Tempo na semana**
> - **Sex 8 mai (chegada):** 19°C máx · 🌧️ trovoada possível, 94% prob. chuva — bom dia para ficar pelo interior, ler na varanda
> - **Sáb 9 mai:** 19°C · ☔ chuva forte (98%) — manhã para o Mercado da Ribeira de Tavira (sábado é dia)
> - **Dom 10 mai (saída):** 18°C · 🌦️ aguaceiros mais leves
>
> **🎭 Acontece na sua estadia**
> - **Sáb 9 mai · Festival do Vinho · Loulé** (Nave do Barão) — concurso de vinhos artesanais + provas regionais. ~45 min de carro.
> - **Dom 10 mai 18h00 · Pedro Jóia · Casa do Sal, Castro Marim** — concerto íntimo de guitarra (português + flamenco). 15 min de carro, hyper-local.
>
> **🐚 Outras dicas para 2 noites curtas**
> - Mercado de sábado em Tavira (manhã de 9 mai) é o melhor para produtos regionais — figo, queijo de cabra, mel
> - Com este tempo, melhor dispensar praia no fim-de-semana — a Praia Verde fica melhor a partir de 3ª
> - Restaurante recomendado para sábado à noite: A Ver Tavira (cobertura coberta, ideal se chover)
>
> *Esta mensagem é gerada automaticamente para complementar a informação de check-in já enviada. Boa estadia!*

### Sample B — Cyril Cuddy (EN) · RMR T1B "Charm & Elegance" · 7 nights · 2026-05-08→15

> *Hi Cyril,*
>
> *Two days until you arrive at our T1B in [property town]. Here's what's happening during your stay — to add to the check-in details we've already sent.*
>
> **🌦️ Weather arc — wet start, warm finish**
> - **Fri-Sun (May 8-10):** 17-19°C, thunderstorms early then showers — indoor/wine-tasting weather
> - **Mon-Tue (May 11-12):** 18-20°C, partly cloudy with light drizzle Tuesday
> - **Wed-Fri (May 13-15):** 21-23°C, sunny — the back half of your week is the beach window
>
> **🎭 What's on, by date**
> - **Fri 8 May 21:00 · 9th Jazz in the Wineries · Convento do Paraíso, Silves** — opening night of the wine-cellar jazz series, ~60 min drive
> - **Sat 9 May · Festival do Vinho · Loulé** — regional wine fair, handmade-wine competition, 45 min
> - **Sat 9 May 21:30 · "A Modern Opera" · Centro Cultural de Lagos** — single performance, ~75 min
> - **Sun 10 May 18:00 · Pedro Jóia (guitar) · Casa do Sal, Castro Marim** — intimate concert, eastern Algarve
> - **Mon 12-Sat 17 May · 9th Algarve Smooth Jazz Festival · Pine Cliffs, Albufeira** — runs across your whole stay, sunset-set format
> - **Throughout May · TRAVESSAS de Lagos** — restaurants offering €20 sharing platters for 4
>
> **🌊 Beaches by week-day** (forecast-driven)
> - Skip the beach Fri-Sun (storms)
> - Mon-Tue: Praia da Marinha or Carvoeiro (sheltered coves, manageable in light wind)
> - Wed-Fri: open windows to Praia da Falésia, Praia Verde — full sun, low UV (5)
>
> **🍴 Worth booking ahead** for sun-week dinners: anywhere in Albufeira old town fills up by Wednesday.
>
> *This message is auto-generated to complement the check-in information already sent. Enjoy the Algarve.*

## Generation pattern (technical)

```
booking → unit → accommodation → property lat/lon
            ↓
   [Open-Meteo forecast]    weather block (PT/EN per language)
   [Open-Meteo marine]      sea temp + waves (if coastal)
   [IPMA tides]             tide-dependent activities (low-tide walks, boat trips)
            ↓
   [events cache (SQLite)]  filter to property region + stay dates
   [static YAML]            weekly markets, season-specific beach picks
            ↓
   [LLM render]             bilingual tip-sheet, language-prioritised per booking.guest_language
            ↓
   [JG approval gate]       gate:concierge_enrichment, 24h timeout
            ↓
   [Resend send]            from concierge@livinstaysalgarve.com (one-way, no reply expected)
```

## Effort + scope

- Data-source layer (Open-Meteo + IPMA + scrapers): **~4h**
- Static YAML for towns + markets: **~2h** (mostly research + JG validation)
- Renderer + bilingual templating: **~2h**
- Approval gate + Resend integration: **~3h** (Resend account setup + transactional template)
- **Total v1**: ~1-1.5 days of focused work
- Recurring cost: €0 (Resend free tier = 3k emails/mo, well above need)

## Hard guards built in

1. **Recipient allowlist at sender level** — environment variable `ALLOWED_RECIPIENT_DOMAINS=jgalhardo.pt,livinstaysalgarve.com` gates every send. To go live, add `*` (or specific domains). Trial mode = JG-only, enforced in Python, not config.
2. **Per-message JG approval** via gate `concierge_enrichment` (24h timeout, OK for T-2 cadence).
3. **No reply path** — concierge@ is send-only. If guest replies, autoresponder routes to the booking engine's existing channel.
4. **Idempotent** — sender SQLite seen-db prevents double-send per booking.
5. **No autonomous claim by HRmanager** — kanban tasks assigned to `joao` (not `personal`), so HRmanager's dispatcher ignores them entirely. (Today's incident root cause.)

## Open decisions for JG

1. **Send domain**: `concierge@livinstaysalgarve.com` (Resend) vs piggyback on `info@`?
2. **Cadence**: T-2 days, T-1, both? Or only T-1 if forecast meaningfully changes between T-2 and T-1?
3. **Per-property contact info**: do you have lat/lon for each accommodation in lsa-pro, or do I need to derive from address?
4. **Approval flow**: still GCApprovalsBot? Or once content shape is signed off, allow auto-send within the rendered template (the *content* is then the gate, not the per-message)?
5. **Static YAML curation**: weekly markets, beach-by-week, restaurant openings — JG to source, or I do an initial draft and JG corrects?