• Keep the current sidebar temporarily while the inline TripDetail editor is stabilized.
• Reuse TripPlannerContext and normalizeStops so Trip edit mode stays aligned with current planner logic.
• Add a single edit-mode toggle before expanding the join flow.
• Make join mode branch by trip visibility:
  • shared / featured trips can expose join
  • private trips should default to private booking
  • owner joins should become add-participants flows with dynamic repricing
• Keep hotel policy rules explicit, with managed vs external handling separated.
• Create the booking layer only after the offer/order snapshot path stays stable.
• Keep Apps Script export endpoints as a later formalized slice.
• Treat FareHarbor as manual execution first, then add calendar validation later.

• line items remain the commercial backbone
• offer and order stay snapshot-based
• document isolation remains intact
• Hotel V1 stays a placeholder
• trip changes stay inside the Trips docs and matching app routes

• Trips plan guide
• Trips next-steps lockfile
• Trip execution plan bundle
• Trip planner refactor target

• Document system: working, but deterministic-state and naming cleanup still need verification.
• Trip core: working, with join-mode nuance and route coverage still being standardized.
• LineItem system: working, but legacy mutation paths still coexist with the normalized pipeline.
• Projection layer: partial but functional for document pagination and projection contracts.
• Trips public surface: partial, with landing and planner surfaces present but still being normalized.
• Offer system: partial, with snapshot creation in place but legacy mutation code still present.
• Order system: partial, with snapshot creation in place but lock discipline still needing hardening.
• TripDays / schedule: working.
• Experience integration: partial.
• Calendar / agenda: partial.
• Apps Script execution: partial.
• TripJoin booking layer: partial.
• Weekly sponsor system: partial.
• Deliverable system: partial.
• AI system: working / partial.
• Dev tooling system: partial.

• BookingBundle execution layer.
• Complete Stripe-backed payment lifecycle.
• FareHarbor bridge as a validated sync/execution layer.

• Editable block-based document system exists.
• Pagination engine separation is in place.
• Autosave pipeline is active.
• AI-assisted document generation works.
• Trip data is embedded and editable in document surfaces.
• PDF export works.

• deterministic block IDs
• no content loss between engine and wagon
• autosave persists without desync
• reload reproduces exact state
• PDF export stays visually stable

• Trip creation from planner and document surfaces exists.
• Trip persists in Prisma.
• TripCities structure works.
• Route composition is functional.
• Pricing estimation pipeline is present.

• stable Trip ID
• idempotent Trip + TripCities persistence
• planner reload reconstructs route correctly
• estimate recalculates deterministically
• Trip existence does not depend on Document

• LineItems are generated from Trip pricing.
• Document -> LineItems pipeline works.
• LineItems are the pricing backbone.

• delete + recreate pattern enforced
• no duplicate LineItems
• totals derived only from LineItems
• sourceType + sourceId traceability complete

• OutputBundle is defined.
• RenderBlocks are defined.
• Trip -> bundle compute works.
• Google Docs and Calendar projection paths are defined.
• Apps Script endpoints are partially integrated.

• bundle is fully serializable
• render output is deterministic
• calendar events are idempotent
• doc export matches RenderBlocks exactly

• Landing builder structure is defined.
• Sections are mapped.
• Read models for trips, cities, and experiences are partially working.
• CTA routing is defined.

• all CTAs route to real pages
• featured trips render from DB
• cities render from DB
• experiences render from DB

• Create Offer from Trip.
• Clone LineItems into Offer.
• Offer acts as a commercial snapshot.

• Offer created from Trip in one action
• LineItems cloned, not referenced
• Offer totals derived from items
• Offer stays immutable after confirmation

• Create Order from Offer.
• Snapshot Offer into Order.
• Lock Offer after conversion.

• Order created atomically
• LineItems snapshot copied
• Offer status updates to ordered
• Order remains immutable

• TripDays are generated from Trip + Cities + Experiences.
• Schedule page is driven by TripDays.

• schedule renders without manual input
• days generate deterministically
• fallback content works
• export uses the same TripDays structure

• Experiences are selectable inside the planner.
• TripCityExperience linking is active.

• attach / detach experiences per city
• pricing reflects selected experiences
• schedule reflects selected experiences

• CalendarEvent internal model is used.
• Trip -> Calendar projection works.

• Trip generates events
• events are idempotent
• map + agenda integration is coherent

• Generic endpoints exist for createDoc, exportPdf, sendEmail, and createCalendarEvent.

• endpoints callable from Next.js
• payload contracts are stable
• responses are stored in Prisma metadata

• User joins Trip -> TripJoin.
• pricingSnapshot freezes at join time.
• shared trip repricing is supported.

• TripJoin created from UI
• pricingSnapshot stored
• pax + rooming supported
• optional Offer can be created from join

• BookingBundle is created after confirmation.
• hotel logic and supplier execution live here.

• bundle created before execution
• status transitions tracked
• separate from Trip

• WeekSlot becomes the monetization layer.
• connects Deliverable, LineItem, and Offer.

• WeekSlot linked to LineItem
• donations accumulate
• deliverable generated from assignment

• Deliverable acts as the projection node.
• unified output storage lives here.

• all exports linked to Deliverable
• Deliverable linked to Trip / Offer / etc
• multiple formats supported

• Order -> payment intent.
• deposit and full payment flows.

• payment intent created
• webhook updates Order
• deposit logic works

• Experience.externalId mapping exists.
• availability validation and booking sync are later layers.

• availability fetched
• mapping stable
• no duplication in DB

• ProjectContact links TripJoin, Offer, and Order.

• contact created once
• contact reused across pipeline
• communication history attachable

• Full route coverage is the target.

• /trips/new
• /trips/[id]
• /trips/[id]/schedule
• /trips/[id]/join
• /offers/[id]
• /orders/[id]
• /projects/[id]

• AssistantThread is operational.
• AI produces structured outputs.

• threads persist
• context and persona applied
• outputs feed compute layer, not DB directly

• DevPrompt is usable for code workflows.

• prompts stored
• outputs linked to files
• reusable for generation pipelines

• Trip planner stays stable.
• LineItems stay deterministic.

• Trip to LineItems output is repeatable
• no surprise recompute paths

• Trip -> Offer -> LineItems snapshot.

• Offer clones items once
• Offer stays snapshot-based

• Offer -> Order -> immutable snapshot.

• Order copies the commercial state
• Offer locks after conversion

• Trip -> Doc + PDF + Calendar working.

• projection targets all render from the same source bundle

• TripJoin + BookingBundle operational.

• join intent and execution stay separated

• Stripe integrated.
• Order lifecycle complete.

• payment updates the canonical order state

• FareHarbor bridge.
• manual and validation flows.

• external distribution never overwrites app truth

• WeekSlot monetization active.

• weekly execution can drive commercial output

• Trip -> Join -> Offer -> Order -> Payment -> Execution -> Projection.

• every stage has a canonical owner and snapshot boundary

This is the in-app document system. It is: an internal application entity editable in the web app rendered through Folio used as orchestration surface used as projection surface used as commercial instrument used as trigger surface for exports and workflows It is not: a Google Doc a DOCX file an external source document the canonical truth for trips, offers, orders, or payments Canonical meaning in code and planning: Document Document2Data Folio document virtual document document instrument

These are external Google Docs used as content sources for publishing systems. They are: external source documents imported or synced into database read models used by the section index / docs publisher used by the single canonical document publisher a convenient content source for cloned or redeployed versions of the app They are not: the in-app virtual document instrument the source of truth for app entities part of Folio editing Canonical meaning in planning: Google Doc external Google document source Google Doc synced Google Doc

These are Google Docs created from app data through Apps Script. They are: projection targets generated from internal entities or virtual documents part of office automation often a step toward PDF, email, calendar, or sharing workflows They are not: editable app truth equivalent to the in-app document system source truth for business state Canonical meaning in planning: export to Google Doc generated Google Doc office document output

These are DB-backed read models used for editorial publishing. They are: cached article records synchronized from sheet/index pipelines or canonical source docs used for public rendering and navigation They are not: the virtual document instrument operational business truth

When discussing development, always name the type explicitly: Virtual Document Instrument = the in-app editable document system Source Google Doc = an external document synced into the app for publishing Generated Google Doc = an external document exported from the app Published Article Record = cached DB article used by section/canonical publishers Magazine Projection = derived editorial/card output, internal or external

Project Virtual Document Instrument Trip Experience Offer Order LineItem Sponsor / WeekSlot / Donation / Assignment publishing / cache entities where relevant

Concept / content layer Entities: ConceptCard CardContent ConceptGroup SessionStack SessionPath Deliverable Role: knowledge study training onboarding scripts posters guidebooks narrative assets Rule: defines what is understood and how delivery is supported does not define pricing, schedules, capacity, or bookings Experience layer Entity: Experience Role: reusable commercial template canonical internal equivalent of a FareHarbor item template Rule: defines what is sold as a reusable unit not time-bound not attendee-bound source for sessions and attachable into trips Session / agenda / operations layer Entities: GroupSession GroupSessionAttendee CalendarEvent AgendaNote MapLocation Role: real scheduled, capacity-bound, operational occurrence Rule: GroupSession is the atomic real-world operating unit trip participants and independent travellers can attend the same session Trip aggregation layer Entities: Trip TripCity TripCityExperience or TripCityPlan TripDay Offer Order Role: bundled multi-city commercial product Rule: Trips compose from Experiences and/or GroupSessions Trips do not define session existence Trips are not the atomic operational unit Locked one-line definition ConceptCards define how it is understood, Experiences define what is sold, GroupSessions define when it happens, and Trips define how it is bundled.

Next.js + Prisma structure action pattern virtual document system projection engine Apps Script starter layer optional sheet/index publishing connectors

Trips Experiences planner pricing / line items landing builder

tailored setup integrations deployment training / onboarding Access modes internal approved open client-instance Deployment modes main Molino internal/showcase deployment trips-focused public deployment boilerplate demo deployment client-specific deployments Standardization required locked folder contract locked action pattern locked projection interface locked Apps Script payload contract reusable pure compute layer separation of reusable vs product-specific modules

Role: editorial / knowledge / multi-section article system Canonical entities: IndexCache Document as indexed cached article records Source model: section-specific sheet indexes linked external Google Docs by id sync pipelines populate DB cache Features: section landing pages indexed document collections sidebar navigation canonical document permalinks section config projection Best for: editorial portals knowledge sites documentation sections magazine-style publishing

Role: one-document publishing engine Canonical entities: SourceDoc Chapter Comment Source model: one canonical external Google Doc synced into DB snapshots / chapter rows Features: one canonical source document chapter / paragraph projection comments by chapter DB-first render background sync + revalidation Best for: books essays serialized blogs commentary editions Rule Keep both publishing systems distinct from the virtual document instrument in planning and implementation.

Goal: ship public trips-facing entry surface Deliverables: /trips landing builder canonical section registry CTA routing featured trips / cities / experiences read models partner route Locked CTA triad: Plan Your Trip Join Featured Trips For Guides & Partners

Goal: turn trips CTAs into working flows Deliverables: /trips/new /trips/featured /trips/[tripId] /trips/[tripId]/schedule estimation Trip + TripCities persistence TripDays generation Experiences as route ingredients

Goal: formalize toolbar/sidebar as execution + composition system Deliver

Status: Master (compiled April 21, 2026) Scope: Full platform — architecture, domain, modules, flows, integrations Philosophy: One source of truth → many projections. Document = Instrument. AI = Tool.

• architecture/20260416_molino-guidebook.md
• architecture/20260420_molino.architecture.md
• document/mlv-document-one_akill.md

A document-driven system that turns ideas, trips, and workflows into real outputs — offers, schedules, and published materials — fast, structured, and repeatable.

System = Deterministic Core + Projection Engine

Prisma (DB)          → single source of truth
Entities             → canonical business objects
Virtual Document     → projection + orchestration surface
Folio                → deterministic renderer
Actions              → only mutation authority
Projection Engine    → external outputs (Google Workspace)
AI                   → tool inside the document, not the core

Truth (Prisma)
    ↓
Document (projection)
    ↓
Folio (render)
    ↓
User / AI Intent
    ↓
Actions (persist)
    ↓
Revalidate
    ↓
Projection (optional)
    ↓
External Systems (Docs / Calendar / Sheets)

One source of truth → many projections.

• UI is minimal
• State lives on the server
• Mutations happen via Server Actions only
• UI updates via Suspense (no page reloads, no client polling)
• No client-side orchestration logic

• Not a dashboard app
• Not an automation marketplace
• Not a CRM or Zapier + AI
• Not a generic document editor

• Daily use by the builder
• One complete workflow end-to-end
• At least one real export (offer / order / trip)
• Users can explain it in one sentence

<a id="chapter-2--architecture-rules-non-negotiable"></a>

• architecture/20260420_molino.architecture.md
• architecture/20260416_molino-guidebook.md
• architecture/20260418_FastProductionSAP_MLV.md
• recap/20260421_trips-spec-audit.md

app/(entity)/<entity>/
  page.tsx        → read-only server orchestrator ONLY
  actions/        → ONLY mutation authority (all Prisma here)
  components/     → dumb UI, client components for state only
  context/        → ephemeral UI state only
  types/          → domain truth, canonical type definitions
  api/route.ts    → external boundary only (no business logic)

1. No Prisma outside actions/ — ever
2. No mutation in pages — pages are read-only orchestrators
3. API routes are external only — no internal business logic in routes
4. One entity = one folder — no cross-entity mixing
5. UI never owns truth — intent flows up, render flows down
6. All writes go through server actions — always, no exceptions

Client intent
→ emitIntent / setForm
→ compute helpers (pure functions, no side effects)
→ queueSave / action
→ Prisma
→ revalidate
→ server re-render via Suspense

rawBlocks (input)
    ↓
FlowUnits (normalized)
    ↓
pagination (layout only)
    ↓
wagons (render)

Guarantees:

• Deterministic IDs
• Pure transforms
• Pagination = layout only, never business logic

<a id="chapter-3--domain-model--entity-stack"></a>

• trips/20260220_trips-sessions-MLV.md
• trips/20260419_trip.specs.md
• trips/20260420_trips-guidebook-plan.md
• trips/20260421_trip-execution-bundle.md
• recap/20260421_trips-spec-audit.md

Project
Virtual Document Instrument
Trip
Experience
GroupSession
Offer
Order
LineItem          ← critical connector
ConceptCard
Sponsor / WeekSlot / Donation / Assignment

Concept / Content Layer

Entities: ConceptCard, CardContent, ConceptGroup, SessionStack, SessionPath, Deliverable

Role: Knowledge, study, training, onboarding, scripts, posters, guidebooks, narrative assets.

Rule: Defines how something is understood and delivered — not how it is scheduled or sold.

Experience Layer

Entity: Experience

Role: Reusable commercial template. Canonical internal equivalent of a FareHarbor item template. City-linked. Not time-bound. Not attendee-bound.

Rule: An Experience is reusable and not date-bound. Source for sessions and attachable into trips.

Session / Agenda / Operations Layer

Entities: GroupSession, GroupSessionAttendee, CalendarEvent, AgendaNote, MapLocation

Role: Real scheduled, capacity-bound, operational occurrences.

Rule: GroupSession is the atomic real-world operating unit. Trip participants and independent travellers may attend the same GroupSession.

Trip Aggregation Layer

Entities: Trip, TripCity, TripCityExperience, TripDay, Offer, Order

Role: Bundled multi-city commercial product — ordered, priced, shared or private, exportable.

Rule: Trips bundle and sequence Experiences and/or GroupSessions. Trips do not define session existence.

ConceptCards define how it is understood, Experiences define what is sold, GroupSessions define when it happens, and Trips define how it is bundled.

LineItem {
  label
  quantity
  unitPrice
  total
  unitType     // e.g. per_person, per_day, per_night, package
  unitLabel    // e.g. "person", "night", "km"
  meta         // breakdown / pricing logic / source metadata
  parentType   // "document" | "offer" | "order"
  parentId
  sourceType   // "trip" | "product" | "experience" | "custom"
  sourceId
}

LineItems are the transferable commercial backbone between Trips and the rest of the commercial system. Used across: documents, offers, orders, reports, exports.

<a id="chapter-4--document-system-virtual-instrument"></a>

• document/SKILL_document-engine.md
• document/GOALS-AHEAD.md
• recap/20260421_trips-next-step-recap.md
• trips/20260421_trips-next-steps.locked.md

• document/mlv-document-one_akill.md
• document/generateTripFromDocument_akill.md
• recap/20260421_trips-spec-audit.md

Critical: The word "document" must always resolve to one of these. Never use it ambiguously.

note2
offer
proforma
invoice
firmorder
custom
trip-offer-v1    ← key template for trip commercial workflow

Each template defines:

{
  (key,
    label,
    emoji,
    requireExplicitEdit,
    defaultData,
    renderView(data),
    renderEditor(data, update));
}

Registered in: app/(pages)/documents2/components/DocRegistryComponents.tsx

{
  title: string,
  description?: string,
  clientName?: string,
  meta: { currency?: string, [k: string]: any },

  // For line-item-aware documents:
  offerId?: number | null,
  offerMode?: "local" | "bound",   // key concept
  lineItemsDraft?: LineItem[]
}

offerMode rules:

• "local" → document stores its own draft line items
• "bound" → document reflects real Offer line items, always live. Read-only except via the Offer editor.

TripOfferTemplate = {
  key: "trip-offer-v1",
  defaultData: {
    contentSections: [
      { id: "intro-letter", type: "text", role: "letter-intro" },
      { id: "itinerary-body", type: "text", role: "itinerary" },
    ],
    ctaSection: {
      enabled: true,
      type: "whatsapp",
      phone: "",
      text: "Click below to open a WhatsApp chat...",
    },
  },
};

The command-driven document system (confirmed working):

DocSection_TripBuilder
    → emits intent flags (never direct side effects)
          _requestInsertIntoLineItems
          _requestOverwriteTripLineItems
          _requestCommitTrip
          _requestPopulateTripOffer
    ↓
Documents2Canvas.handleTripSectionChange
    → the ONLY coordination point
    → interprets intents
    → calls server actions
    → queues save
    ↓
Server Actions
    → commitTripFromDocument
    → syncTripLineItems
    → populateTripOfferFromTrip
    → createOfferFromTripFlow
    ↓
Prisma (truth)
    → revalidatePath

Key invariant: DocSection_TripBuilder has zero persistence knowledge. It only emits intents.

<a id="chapter-5--trip-module-builder--engine--planner"></a>

• trips/20260420_trips-guidebook-plan.md
• trips/20260420_trips-plan.md
• trips/20260420_trip-planner.current-pattern.md
• trips/20260420_trip-planner.refactor-target.md
• trips/20260421_trip-execution-bundle.md
• recap/20260421_trips-next-step-recap.md
• trips/20260421_trips-next-steps.locked.md

• trips/20260419_trip.specs.md
• trips/20260420_trip-planner.current-pattern.md
• trips/20260420_trip-planner.refactor-target.md
• trips/20260421_trip-execution-bundle.md
• recap/20260421_trips-next-step-recap.md

Trip Planner =
  Builder     → deterministic form + normalization
  Engine      → pricing + projection
  Execution   → real-world booking + confirmation

Trip ≠ Booking
Trip = plan
Booking = execution

Client
→ TripPlannerContext
→ normalizeStops()
→ setForm
→ (create | update)TripFromPlanner
→ Prisma
→ revalidate
→ Trip Engine (pricing, days, lineItems)
→ UI

+ Execution Layer:
Trip
→ BookingBundle
→ Ops (Apps Script / Manual / FareHarbor)

form.stops[] = canonical route

Each stop:
  cityId
  nights
  computed role     // NEVER user-controlled
  services          // transport, guide, tours

• index 0 → arrival
• last index → departure
• Córdoba + Granada → core
• else → extension

• normalizeStops() — no duplicate cities, core cities always present
• computeDisplayRole() — stable ordering
• businessRank() — valid nights constraints

app/trips/new/
  page.tsx
  actions/
    tripPlanner.actions.ts
    tripPlanner.read.actions.ts
  components/
    TripPlannerShell.tsx
    TripPlannerSidebar.tsx
    TripPlannerMain.tsx
    TripPlannerStepper.tsx
    TripPlannerSummary.tsx
    TripPlannerSchedulePreview.tsx
    TripPlannerCostPreview.tsx
    TripPlannerDock.tsx
  context/
    TripPlannerContext.tsx
  types/
    tripPlanner.types.ts

Remove stepper/sidebar. Replace with inline sections:

1. Basics
2. Route (table model — row = stop)
3. Services (per city, dropdown)
4. Hotels (auto-calc on pax change)
5. Options

No step navigation. Data flow unchanged. See 20260420_trip-planner.refactor-target.md.

// Location: app/(pages)/documents2/actions/commitTripFromDocumentAction.ts
export async function commitTripFromDocumentAction({
  documentId,
  projectId,
  tripDraft,
}) {
  // Auth → load doc → extract trip data → upsert Trip → create TripCities → return { tripId }
}

Key: Uses draftId as upsert key for idempotent commits.

// Location: app/(pages)/lineitems/actions/syncTripLineItems.ts
// Upserts by (tripId, key) — orphaned items deleted
// Requires: @@unique([tripId, key], name: "tripId_key") in Prisma schema

TripCard {
  id            // slug (e.g. cordoba-granada-core)
  title
  summary
  phase         // MLV_PHASE_1 | MLV_PHASE_2
  visibility    // public | unlisted | private
  cities[]
  sequence[]    // ordered SessionCard refs with dayIndex + required flag
  duration      { days, nights }
  cadence       // weekly | monthly | fixed-dates
  basePriceEUR
  pricingModel  { type: "bundle", includes, excludes }
  joinModes[]   // shared | private | assisted
  groupLogic
}

• Sessions may run with or without a trip
• Trips reuse existing sessions at bundled rates
• Pricing differs by participation mode, not session identity

Modes: included | excluded | estimate_only

Rule: Hotel logic must remain pluggable and optional without destabilising trip truth.

Prices can improve as more participants join. Group economics affect per-traveller outcome. This is a real commercial behavior — not a side note.

<a id="chapter-6--offer--order--invoice-pipeline"></a>

• document/GOALS-AHEAD.md
• roadmap/16DecTuesdayWeekGoals.md
• trips/20260421_trip-execution-bundle.md
• recap/20260421_trips-spec-audit.md

Trip (with LineItems)
    ↓
Offer (createOfferFromTripFlow)
    ↓
Order (confirmed, line items COPIED not referenced)
    ↓
Invoice (delivered quantities + payment state)

• Only Offer runs pricing transforms. Orders and invoices receive copied line items with no re-pricing.
• Offer → Order: line items are copied, order totals computed once, order may modify quantities independently.
• Order → Invoice: adjusts delivered quantities, payment state, due amounts.

getOfferWithLineItems(offerId)         // returns live items + computed totals
createOfferFromDocument(documentId)    // local draft → new Offer → bind document
bindDocumentToOffer(documentId, offerId)
detachDocumentFromOffer(documentId)    // copy canonical → local mode
updateOfferLineItemsFromEditor(offerId, items[])
createOfferFromTripFlow({ tripId, documentId })  // full flow action
copyTripLineItemsToOffer({ documentId, tripId, offerId })

Universal transformer: resolvePricing(sourceType, sourceId, context) → LineItemPackage

LineItemPackage {
  packageTotal: number
  defaultUnitType: string
  defaultUnitLabel: string
  rows: [{ title, qty, unitType, unitLabel, unitPrice, meta? }]
}

Source types: "trip" | "product" | "experience" | "custom"

<a id="chapter-7--ai-personas--contexts"></a>

• framework/seeds/seed.molino-app.skills.md
• framework/seeds/seed_.txt
• framework/seeds/reseedEntities.txt
• document/GOALS-AHEAD.md

• AI outputs must conform to schemas
• No free-text automation touching integrations
• Human confirmation required for all side effects
• AI is a tool inside the document, not the core

✅ Fill structured forms (typed + validated) ✅ Generate document content via personas ✅ Assist planning (summaries, drafts, variations) ✅ Rewrite intro letters, itinerary paragraphs ✅ Explain pricing to clients ✅ Generate alternative wording

❌ Parse Tally payloads ❌ Decide pricing ❌ Build line items ❌ Touch integrations directly

default    → concise, structured, helpful
developer  → clean typed code, Next.js App Router conventions

<a id="chapter-8--projection-layer-apps-script--google-workspace"></a>

• appscript/archive/SKILL_projection-appscript.md
• appscript/appscript.apis.md
• appscript/appscript-office-server-firstLoop.md

• appscript/archive/SKILL_projection-appscript.md
• appscript/appscript.apis.md
• appscript/appscript-office-server-firstLoop.md
• document/GOALS-AHEAD.md
• recap/20260421_trips-spec-audit.md

Principle: Compute in Next.js → project externally via Apps Script.

Request envelope:

type GoogleToolRequest<TInput = unknown> = {
  action: string; // e.g. "docs.create", "gmail.send"
  requestId: string; // trace ID
  source: "folio" | "trip" | "product" | "experience" | "offer" | "assistant";
  entityType?: string;
  entityId?: string | number;
  documentId?: number;
  userId?: string;
  payload: TInput;
};

Response envelope:

type GoogleToolResponse<TResult = unknown> = {
  ok: boolean;
  action: string;
  requestId: string;
  timestamp: string;
  result?: TResult;
  error?: { code: string; message: string; details?: unknown };
  meta?: { fileId?, fileUrl?, rowsProcessed?, durationMs?, ... };
};

POST /api/tools/google/gmail/send
POST /api/tools/google/docs/create
POST /api/tools/google/docs/export-pdf
POST /api/tools/google/sheets/append
POST /api/tools/google/calendar/create

Available actions (via doPost router):

• docs.create, docs.exportPdf, docs.appendContent, docs.replaceContent
• gmail.send, gmail.createDraft, gmail.reply
• sheets.create, sheets.appendRows, sheets.getRows, sheets.logActivity
• calendar.createEvent, calendar.updateEvent, calendar.listEvents
• drive.createFile, drive.copyFile, drive.shareFile, drive.exportFilePdf
• coreOffice.generateTemplates, coreOffice.generateEntityDocs

createTripAgendaAndInviteGuests
publishOfferAsPdfAndEmail
logMeetingAndCreateFollowup
buildClientBriefAndShare
createTripDaySchedule
sendPostSessionSummary

These call the generic GAS endpoints through Next server actions — never from the client.

type OutputBundle = {
  meta: { entity: string; entityId: string; title: string };
  document?: DocumentPayload;
  calendar?: CalendarPayload[];
  tabular?: TabularPayload;
};

Trip export paths:

Trip → PDF → (via Apps Script)
Trip → Google Doc → (generated document)
Trip → Email → (via gmail.send)
Trip → Calendar event → (via calendar.createEvent)

<a id="chapter-9--external-integrations"></a>

• integrations/places-integration_akill.md
• integrations/tally-integration-startert_akill.md
• integrations/tally-forms-integrations-2part_akill.md
• recap/20260421_trips-spec-audit.md

External channels = projections, not truth. External systems may consume, reflect, or publish trip outputs, but they must not define internal model boundaries or internal truth.

Tally = External Draft Input Adapter. Not a document generator.

Flow:

Tally form submitted
    ↓
Client-side: Tally.openPopup() with onSubmit handler
    ↓
POST /api/tally (or /api/webhooks/tally)
    ↓
mapTallyToTripDraft(payload) → TripDraftData
    ↓
Create Document (type: "trip-offer-v1") with tripSection.tripData
    ↓
Return documentId → redirect to document editor

Key mapper:

// app/lib/tally/mapTallyToTripDraft.ts
export function mapTallyToTripDraft(payload: TallyPayload): TripDraftData {
  const get = (label) => payload.fields.find(f => f.title === label)?.answer?.value ?? "";
  return { id: crypto.randomUUID(), title: get("Trip title"), pax: Number(get("Participants") || 1), ... };
}

Pattern: Next.js API route → Google Places Text Search → process results → return to client.

GET /api/fetchPlaces?query=...
→ Google Places API (textsearch + details)
→ { name, location, url, details: { phone, website } }[]

Or via Apps Script Web App deployment for GAS-side processing.

Role: Inventory only. External booking bridge.

• Sessions = sellable experiences (standard rate / bundled rate)
• Trips = bundled event products
• Rule: FareHarbor is a projection target, not internal truth.

Spanish official accounting integration. Export structured invoice data.

Independent commerce exports. Structured data export only. No universal Zapier-style mappings in v1.

<a id="chapter-10--public-surface-trips--al-andalus-experience"></a>

• trips/20260420_trips-guidebook-plan.md
• trips/20260419_trip.specs.md
• trips/20260220_trips-sessions-MLV.md
• trips/20260421_trip-execution-bundle.md

• trips/20260419_trip.specs.md
• trips/20260420_trips-plan.md
• trips/20260420_trip-planner.current-pattern.md
• trips/20260420_trip-planner.refactor-target.md
• recap/20260421_trips-next-step-recap.md

Externally: Al-Andalus Experience (trips, city experiences, shared departures, local sessions, travel planning, partner network). Internally: powered by the broader Molino platform (backstage).

• Attract — route user intent (custom trip / shared trip / city browse / partner connect)
• Compose — assemble routes and city experiences into real trip products
• Sell — estimates, offers, booking paths, shared-trip participation
• Operate — scheduled sessions, attendance, trip days, rooming, confirmations
• Project — trip schedules, offer documents, PDFs, email/calendar packages

1.  trip_hero                   → CTAs: Plan Your Trip / Join Featured Trips / For Partners
2.  trip_pathways               → Route users by intent
3.  trip_how_it_works           → Explain city-rhythm/shared-session model
4.  trip_featured_group_trips   → Real joinable inventory
5.  trip_featured_cities        → Cities as hubs (Córdoba, Granada, ...)
6.  trip_featured_experiences   → Reusable commercial units
7.  trip_plan_your_trip         → Custom trip planner CTA
8.  trip_for_partners           → Supply-side and network entrypoint
9.  trip_updates                → News/updates
10. trip_final_cta              → Conversion close

• app/trips/page.tsx is the fetch/orchestration layer. It reads the landing sections and the trip lists once, then passes the resolved arrays into TripsSectionRenderer.
• TripFeaturedTripsSection is the composition point for the landing page trip block. It can render the core landing content first and then append the database-backed trips below it.
• For this route, the lower trip list should stay a render-time continuation, not a section-content array that editors need to maintain manually.
• Keep the landing-page editing and persistence flow unchanged. This pattern only affects how the featured trips section projects fetched trip data into the public trips landing page.

• app/trips/[tripId]/page.tsx now owns the main trip detail experience and renders the trip builder surface inside the page body through TripDetailClient.
• Inside TripDetailClient, the Trip configuration section is treated as an on-demand editor surface. It stays collapsed unless edit mode is active, so the public trip detail layout remains clean.
• app/trips/new/page.tsx and app/trips/[tripId]/edit/page.tsx both use TripPlannerShell, which keeps the create/edit builder experience consistent.
• The intent is to avoid the old bespoke /trips/new layout drift and keep the route-specific builder UI aligned with the shared trips body pattern.

app/
  └── trips/
      ├── page.tsx
      ├── actions/
      │   └── tripsLanding.actions.ts
      ├── components/
      │   ├── TripsLandingSurface.tsx
      │   ├── TripsSectionRenderer.tsx
      │   └── sections/
      │       ├── TripHeroSection.tsx
      │       ├── TripPathwaysSection.tsx
      │       ├── TripHowItWorksSection.tsx
      │       ├── TripFeaturedGroupTripsSection.tsx
      │       ├── TripFeaturedCitiesSection.tsx
      │       ├── TripFeaturedExperiencesSection.tsx
      │       ├── TripPlanYourTripSection.tsx
      │       ├── TripForPartnersSection.tsx
      │       ├── TripUpdatesSection.tsx
      │       └── TripFinalCTASection.tsx
      ├── hooks/
      └── types/
          ├── tripsLanding.types.ts
          └── tripsLanding.registry.tsx

• 4 calendar days
• 3–4 nights, arrival/departure dependent
• Day 0 — arrival & warm-up (non-mandatory)
• Days 1–3 — guided core (Day 1 Córdoba, Day 2 Medina Azahara + road, Day 3 Granada)

Avoid fixed nights. Use: "4-day guided cultural sequence with flexible arrival & departure"

• Sessions = sellable experiences (standard rate → public participants)
• Trips = bundled event products (bundled rate → trip participants)
• Same session, different rate tiers

<a id="chapter-11--current-implementation-status--next-steps"></a>

• recap/20260421_trips-next-step-recap.md
• recap/20260421_trips-spec-audit.md
• trips/20260421_trips-next-steps.locked.md
• trips/20260421_trip-execution-bundle.md

• roadmap/16DecTuesdayWeekGoals.md
• document/GOALS-AHEAD.md
• trips/20260420_trips-guidebook-plan.md
• recap/20260421_trips-next-step-recap.md
• recap/20260421_trips-spec-audit.md

• Document pagination (stable enough for continued work)
• AI document generation (stable enough for product work)
• Trip section generation inside virtual documents ✅
• Dynamic trip cost estimation → line items ✅
• PDF export ✅
• Trip planner route (in construction, working core) ✅
• Document Editor (page-fit / width-fit behavior) ✅

1. Trip → DB Entity (commitTripFromDocument)

// Prisma: Trip model with draftId @unique
// Action: commitTripFromDocument({ documentId, tripDraft })
// Integration: Documents2Canvas.handleTripSectionChange
// Status: Pattern proven, active implementation

2. Trip → Offer → Order Sequence

// createOfferFromTrip → copyTripLineItemsToOffer → createOfferFromTripFlow
// Offer model: { tripId, documentId, status, currency, lineItems }
// Status: Actions defined, wire-up in progress

3. Trip Planner Standalone Route

// app/trips/new/ → TripPlannerShell
// createTripFromPlanner + updateTripFromPlanner
// TripDays projection from stops
// Status: In construction

• Section ordering edge cases
• Occasional overflow splitting awkwardness
• Page-fit layout polish
• Hidden/default section behavior cleanup

1. Stabilize trip entity persistence + planner route
2. Offer builder bridge from canonical trip line items
3. Booking / payment continuation using canonical pricing
4. Hotel mode improvement (included / excluded / estimate_only)
5. TripCityExperience integration into engine input
6. Apps Script output automation (Docs, PDF, Calendar)
7. FareHarbor API integration
8. Public trips landing (Al-Andalus Experience surface)
9. Exports and asset-family outputs
10. Sponsor system + channel overlays

• ❌ Do not merge ProjectSection and Section
• ❌ Do not rebuild the builder from scratch
• ❌ Do not over-permission Spaces
• ❌ Do not add AI to core pricing logic
• ❌ Do not add universal Zapier-style mappings