cocottetech/@platform/codebase/@features/ai-copilot/docs/hotel-scout.screen.md

hotel-scout.screen

Hotel scouting — the bookings-hotels specialist's primary interaction surface for brief R §R1c. Scouted via Tor-pool Playwright per v2's tour-scout worker (ported per brief J). Reached from tour-leg-detail.screen.md hotel card or via "open scout" from chat. Voice register: working — analytical and precise; safety language uses plain register.

Layout (full-screen drawer)

┌─────────────────────────────────────────────────┐
│ ◄ Berlin · Oct 3–7                  ⚙ filters  │ 56pt — top bar
├─────────────────────────────────────────────────┤
│                                                 │
│  ─── Filters active ───                         │
│  Budget ≤ $250/n · safety ≥ medium ·            │   active filter pills
│  walkable to venue · independent · no chains    │
│                                                 │
│  ─── Shortlist · 2 ───                          │   considering
│  ┌─────────────────────────────────────────────┐│
│  │ Hotel Riehmer · $185/n                       ││
│  │ ✓ safety OK · ✓ walkable · ✓ independent     ││
│  │ Last scouted 2h ago                          ││
│  │ [ Open detail → ]                             ││
│  └─────────────────────────────────────────────┘│
│  ┌─────────────────────────────────────────────┐│
│  │ Hotel Mitte · $210/n                         ││
│  │ ✓ safety OK · ✗ walkable (1.4 km) · ✓ indep. ││
│  │ Last scouted 6h ago                          ││
│  │ [ Open detail → ]                             ││
│  └─────────────────────────────────────────────┘│
│                                                 │
│  ─── Scout queue · 3 in flight ───              │
│  ⌛ Hotel Adlon · scouting via Tor pool          │   live progress
│  ⌛ Hotel de Rome · queued · 4 ahead             │
│  ⌛ NH Berlin · circuits exhausted, retrying     │
│                                                 │
│  ─── Skipped · 6 ───                            │   collapsible
│  [ Show skipped ▾ ]                             │
│                                                 │
│  [ + Scout another hotel ]                      │   manual add
│  [ ↻ Refresh shortlist ]                        │
│                                                 │
└─────────────────────────────────────────────────┘

Components

Component	Notes
Top bar	Back to tour-leg-detail; filter cog opens filter sheet.
Filter pills	Active filter chips; tap × to remove.
Shortlist card	Per-hotel: name + nightly + safety check chips + walkable / independent / no-chains + last-scouted timestamp + "open detail" CTA.
Scout queue	Real-time progress of in-flight Playwright scouts via the Tor circuit pool (per v2 tour-scout port). Status per row: "scouting / queued / circuits exhausted / failed."
Skipped list	Collapsed by default. Hotels Quinn or Cocotte ruled out; reason chip per row.
Manual + refresh	Scout another (Quinn names a hotel) / Refresh (re-scout the shortlist).

States

1. Empty (just opened, no shortlist yet) — bookings-hotels working banner: "Scouting Berlin hotels through Tor pool. First results in ~2 minutes."
2. Shortlist populated (default) — 2–5 hotels in shortlist; queue still active behind.
3. No acceptable hotels found (per brief R "dead-end") — red banner: "I couldn't find hotels matching your filters in this date range. Soften filters or extend dates?" Filter sheet pre-opens.
4. All circuits exhausted — banner: "Tor pool saturated; retrying in 5 min. Or try other dates."
5. Scout-in-flight — queue section showing progress; live updates every 15s.
6. Hotel chosen / booked — banner: "Hotel Riehmer booked. Other shortlist hotels archived. [Cancel booking]"
7. Hotel safety flag triggered (per K §K4 jurisdiction or N coop intel on the hotel's location) — pulse red on the affected card with explainer chip.
8. Manual hotel rejected (Quinn typed a name; bookings-hotels can't reach it OR found a safety issue) — inline error: "Hotel X failed safety check. Reason: {flag}. Add anyway?"
9. Reduced motion — sparkline-free; live progress is text-only.
10. VoiceOver — shortlist read first; queue announced as live region.

Interactions

• Tap a shortlist card → "Open detail" → hotel-detail sheet (deeper card: photos, neighborhood, safety detail; not yet a dedicated screen).
• Long-press a shortlist card → "Mark booked" / "Move to skipped" / "Re-scout now."
• Tap a skipped row (when expanded) → "Re-consider" affordance.
• Tap "+ Scout another hotel" → input sheet for hotel name + city; routes to scout queue.
• Tap filter cog → filter editor (budget, safety floor, walkable radius, independent-only toggle, chain blacklist).
• Pull-to-refresh → re-pull current state from the worker.

Edge cases

• Tor pool failing entirely (per brief M §M2) — banner: "Tor scouting is down. Falling back to direct lookups (less anonymous)." Quinn can opt in or out.
• Hotel match against coop intel — N intel flagged this hotel in a coop Quinn belongs to → card uses red pulse + reason chip: "🛡 Flagged in Berlin coop — see report." Tap → coop-intel-detail.
• Same hotel scouted across multiple tour legs — auto-merges Quinn's history of this hotel ("Last stayed: previous Berlin leg, May 2025"). Subtle chip.
• Date range conflict (hotel not available on those dates) — card grays with "unavailable for these dates" chip; offers re-check on date change.
• Filter eliminates all shortlist hotels — banner: "Tightened filters hide all hotels. Loosen or restart scout." Doesn't auto-rescout (could be expensive).

Related

• Brief R §R1c — parent design.
• specialist-bookings-hotels.contract.md — the specialist driving scout.
• tour-leg-detail.screen.md — parent screen.
• Brief K §K4 — jurisdiction filter source.
• Brief N — coop intel may flag specific hotels.
• Brief J _engineering — v2 tour-scout worker port.

Out of scope

• Booking the hotel itself (separate flow; Cocotte hands off to a booking URL or contacts directly).
• Hotel-detail screen interior (photos, neighborhood map, etc.).
• Multi-traveler coordination (single-Quinn at P0).