Molino⺢ Practice

H1🎯 HUMAN LAYER DOC — COMMERCIAL CONVERSION LOCK

Status: ACTIVE — Economic lanes only
Last updated: 2026-05-11
Authority: This doc supersedes all prior human-layer notes for commercial decision-making.

H2Mission

Ship the lowest-friction commercial engine for all intended niches and user segments. Every line of code, every button, every pricing row must serve one purpose: convert intent into booking or payment.

Travel is deeply personal. Our wording must resonate with the traveller's mindset — not thrown like corn to chickens. This tone must be carried everywhere: trips, experiences, landing pages, emails, and payment confirmations.

H2Commercial Architecture: Full Flow

DISCOVERY → PLANNING → PRICING → EXECUTION
(trips/public) (trips/[id]) (trip-engine) (Stripe/FareHarbor)

The trip detail page (/trips/[tripId]) is the critical conversion hub. It must:

Sell the journey — hero, itinerary, city content that makes travellers want to join
Show transparent pricing — per person, ground services, hotel estimates
Present clear actions — Join / Deposit / Full payment / FareHarbor (for featured)
Build trust — editorial tone, no hidden fees, clear what's included

H21. FareHarbor Layer — External Booking Bridge

Account: alandalus-experience
Confirmed: Córdoba (617917), Granada (617919), Full journey (618992)
Missing: Madrid, Málaga, Sevilla — need FareHarbor item IDs
Script: loaded on trips landing, experiences, and trip detail (for featured trips with bookingHref)

Trip detail behaviour:

Featured trips with bookingHref → show "Book this trip" (FareHarbor lightframe) + "Or pay directly →" (Stripe)
Public trips without FH → show Stripe join flow only
Private trips → no public booking

Next: Map remaining cities → verify lightframe loads → add fallback when FH fails

H22. Stripe Layer — In-App Payments

Trip detail join panel (TripJoinPanel.tsx):

User selects participants + rooms
Chooses: Deposit (€250/person) / Full / Ground only
createBookingWithStripe() → Stripe Checkout Session → redirect
Webhook /api/webhooks/stripe updates Order → success page

Environment:

STRIPE_SECRET_KEY=sk_...
STRIPE_WEBHOOK_SECRET=whsec_...  ← NEEDED IN VERCEL
NEXT_PUBLIC_APP_URL=https://...

Next: Set webhook secret in Vercel → add confirmation email → add retry logic

H23. Pricing Display on Trip Detail

Current:

Per-person price shown in hero stats grid
Join panel shows: route, per-person cost, group total, hotel estimate, deposit amount
Estimate workspace (editor-only) shows full line-item breakdown

Must show transparently:

Ground services per person (what they're paying for)
Hotel estimate (separate, confirmed later)
Deposit hold vs full payment options
What's included vs what's estimated

Next: Wire experience pricing engine into experience cards on trip detail

H24. Trip Detail Page — Content & Style Needs

H3Hero Section

✅ Full-bleed background image with dark gradient overlay
✅ Full-width content (max-w-7xl)
✅ Larger fonts, readable
✅ Route badges, stats grid
✅ Poster/hero dual toggle for admins
✅ Poster mode: full-bleed image with white overlay + text, or solid color when no image
✅ Hero uses backgroundImage CSS for reliability (Next.js fill was fragile in this layout)

H3Itinerary Section

✅ Editorial tone (city-specific warm descriptions)
✅ City content from City model rendered in canonical canvas
✅ Full description, no truncation, rounded-2xl bg-[#faf6f0] cards
✅ City images fixed — replaced broken Unsplash URLs with Picsum, added onError fallback
✅ Removed black-square image containers (bg-[#111] softened to bg-neutral-800)
Still needed: Visual polish — better spacing, typography hierarchy

H3Join / Booking Section

✅ Deposit / Full / Ground-only buttons
✅ Room selection (double/single)
✅ Price breakdown
Still needed:
- FareHarbor button for featured trips (dual channel)
- Better visual hierarchy — pricing should feel like a natural conclusion to the itinerary
- Trust signals (secure payment, cancellation policy hints)

H3Commerce / Export (Editor-only)

✅ Removed raw "Offer bridge" dev-map from main canvas
✅ Commerce actions moved to TripEditDock (create offer, view offers, checkout, export)
✅ Estimate workspace stays dock-triggered, copy rewritten to user voice

H3Experience Content (if linked)

✅ Rewrote "Experience content" → "What's included"
✅ Editorial tone applied to concept groups/cards
Still needed: Full editorial presentation with imagery

H25. Commercial User Flows

H3Flow A: Group Trip Booking

/trips → Browse public trips → /trips/[tripId]
  → Read itinerary + pricing
  → Click "Join this trip"
  → Select participants + rooms
  → Choose: Deposit / Full / Ground only
  → Stripe checkout
  → Success → Booking confirmation

H3Flow B: Experience Booking

/trips → Featured experiences → /experiences/[experienceId]
  → Read description + pricing
  → Click "Book now" (FareHarbor)
  → FH lightframe opens
  → Select date + participants
  → Complete booking on FareHarbor

H3Flow C: Custom Trip Planning

/trips → "Plan your trip" → /trips/planner
  → Add cities, dates, group size
  → Select services
  → View live pricing estimate
  → Generate offer / Share link

H26. Communication Tone & Blacklist

Always adopt the traveller's point of view. They are looking for a solution; we show it to them and intuitively enable conversion.

H3Forbidden words (dev-speak)

bridge, layer, lane, flow, workspace, pipeline, backend, frontend, map for, developer, editor surface, editing surface, project-level, content stack, projection, session path, concept card, JSON, migration, fallback, DB, database, Prisma, schema, endpoint, API, handler, canonical, builder data, line item, projected, operational booking, deliverable, hierarchy, post-booking, rich content, structured content, experience content, editable content, commercial flow

H3Preferred replacements

Don't say	Say instead
Offer bridge	Generate offer
Estimate workspace	Cost breakdown / Your trip estimate
Projected total	Estimated total
Line item	Item / cost
Content stack	What's included / Experiences
Session path	Journey style
Concept card	City experience
Linked concept card	Rich description / Experience detail
Commercial flow	Booking / Payment
Operational booking concerns	Accommodation confirmed later

H3Tone rules

"Reserve your place" not "Book now"
"Your journey through Andalusia" not "Tour package"
"Travellers joining this trip" not "Customers"
Show total transparently — no hidden fees
Solo travellers → joining groups; Group organizers → customization; Families → flexible pacing

H27. Done / Shipped

✅ Trip pricing engine with all cost categories
✅ Stripe checkout (deposit / full / ground)
✅ FareHarbor lightframe integration
✅ Public trips gallery — masonry + grid views, QR badges
✅ Poster/Grid style spec locked
✅ Trip detail hero — full-bleed image, dark overlay, poster/hero dual toggle
✅ Editorial itinerary — city-specific warm narrative copy
✅ City block content selector — links TripCity → City records
✅ /api/cities endpoint
✅ Trip dashboard image editing
✅ QR code generation (120×120 in grid views)
✅ Masonry columns locked at 4 max at all breakpoints
✅ Commerce/export tools moved from main canvas to TripEditDock
✅ Dev-speak blacklisted from all user-facing copy (bridge, layer, lane, flow, workspace, etc.)
✅ Itinerary image black squares fixed (Unsplash → Picsum, onError fallback)
✅ Trip detail page layout — full-width, shifts 320px when sidebar opens, centered in remaining space
✅ Content linking system — concept cards + session paths wired via JSON fallback
✅ Travevy itinerary canvas — full-width stacked layout, concept card content rendered

H28. Next Immediate Actions

H3Critical (Blocks Revenue)

Map remaining FareHarbor cities — Madrid, Málaga, Sevilla item IDs
Set STRIPE_WEBHOOK_SECRET in Vercel — production webhook verification
Test Flow A end-to-end (browse → join → pay → confirm)
Test Flow B end-to-end (browse experience → FH booking)

H3Trip Detail Page Polish

Join panel refinement — FareHarbor dual-channel button for featured trips, trust signals, clearer pricing hierarchy
Experience content presentation — Editorial styling for concept groups/cards with imagery
Itinerary visual polish — Improve spacing, typography hierarchy, day-level imagery

H3Commercial Flow Completion

Wire experience pricing into /experiences/[experienceId] page
Add booking confirmation email after Stripe success
**Design sponsorship subscription tiers

H29. Non-Commercial Archive

All prior items moved to:

dev-docs/_PRD/human-layer-post-commercial-archive.md

Rule: No non-commercial work enters this doc.

Locked for commercial conversion. All changes must serve a booking or payment flow.

human-layer-doc

Master Codebase Guidebook
Markdown + HTML Dev-Docs Renderer - Frontend Client Module