tripkit 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Peter Kwidzinski
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,213 @@
+# 🗺️ TripKit
+
+**Open-source framework for AI-assisted trip planning with beautiful interactive visualizers.**
+
+TripKit is a structured data schema + rendering engine that turns trip plans into stunning interactive maps with day-by-day itineraries. It works with any AI agent (Claude, GPT, Gemini) or can be filled in manually.
+
+<p align="center">
+  <img src="docs/screenshot.png" alt="TripKit Visualizer" width="800">
+</p>
+
+## Why TripKit?
+
+Most trip planning tools give you either:
+- **A map with pins** (no context, no schedule, no restaurants)
+- **A text itinerary** (no visual, hard to share, impossible to navigate from)
+
+TripKit gives you **both** — a Leaflet interactive map with route polylines, stop markers, and hotel markers, alongside a rich sidebar with weather, meals, lodging confirmations, alerts, and pro tips for each day.
+
+Born from a real 6-day Oregon road trip planned iteratively with AI. Every feature exists because we needed it on the road.
+
+## How It Works
+
+```
+┌─────────────────────────────────────────────┐
+│  1. QUESTIONNAIRE                           │
+│     Conversational elicitation → Trip Brief  │
+├─────────────────────────────────────────────┤
+│  2. RESEARCH & PLANNING                     │
+│     Trip Brief → Trip Plan (YAML)           │
+├─────────────────────────────────────────────┤
+│  3. RENDER                                  │
+│     YAML → Interactive HTML or React app    │
+├─────────────────────────────────────────────┤
+│  4. ITERATE                                 │
+│     Feedback → Updated YAML → Re-render     │
+└─────────────────────────────────────────────┘
+```
+
+**The YAML schema is the product.** Renderers are interchangeable. The AI layer is optional but powerful.
+
+## Quick Start
+
+### Option 1: One-liner via `npx` (recommended)
+
+**Prerequisite:** [Node.js](https://nodejs.org) 18 or newer. No install, no clone.
+
+```bash
+npx tripkit my-trip.yaml my-trip.html
+open my-trip.html
+```
+
+That's it — `npx` fetches TripKit on first run and caches it. Use any YAML path on your machine.
+
+### Option 2: Clone the repo (for hacking on the renderer)
+
+```bash
+git clone https://github.com/piti/tripkit.git
+cd tripkit
+npm install
+node convert.js examples/oregon-spring-2026.yaml my-trip.html
+open my-trip.html
+```
+
+### Option 3: With an AI Agent (everyone)
+
+1. Start a conversation with your preferred AI agent (Claude recommended)
+2. Share the `agent/AGENT-SKILL.md` as context
+3. Tell it about your trip: _"I'm planning a 5-day road trip through the Pacific Northwest with my family..."_
+4. The agent uses the questionnaire to gather details, researches routes/hotels/restaurants, and generates a TripKit YAML file
+5. Convert to HTML with `npx tripkit your-trip.yaml`, or ask the agent to render it directly
+
+### Option 4: Manual (no AI needed)
+
+1. Copy `examples/oregon-spring-2026.yaml` as a starting template
+2. Edit with your own trip data
+3. Run `npx tripkit your-trip.yaml`
+4. Open the generated HTML file
+
+## Project Structure
+
+```
+tripkit/
+├── schema/
+│   └── tripkit.schema.yaml      # Data contract — the spec
+├── examples/
+│   └── oregon-spring-2026.yaml  # Complete real-world example
+├── renderers/
+│   ├── html/
+│   │   └── tripkit-renderer.html  # Self-contained HTML renderer
+│   └── react/
+│       └── (coming soon)          # React component library
+├── agent/
+│   ├── questionnaire.yaml       # Elicitation template
+│   └── AGENT-SKILL.md           # System prompt for AI agents
+├── docs/
+│   └── screenshot.png
+├── convert.js                   # YAML → HTML CLI tool
+├── package.json
+└── README.md
+```
+
+## Schema Overview
+
+The YAML schema captures everything needed for a complete trip plan:
+
+```yaml
+trip:           # Title, dates, travelers, origin
+days:           # Array of day plans, each containing:
+  - number      #   Day number
+    title       #   Route summary
+    date        #   Date string
+    status      #   completed | active | upcoming
+    color       #   Map route color (hex)
+    summary     #   Drive time, hike time, miles
+    weather     #   Forecast (filled closer to trip)
+    meals       #   Breakfast, lunch, dinner recommendations
+    lodging     #   Hotel name, confirmation, coordinates
+    alerts      #   Warnings (road closures, age restrictions)
+    tips        #   Pro tips from experience
+    stops       #   Array of stops with lat/lng, descriptions, nav links
+routes:         # Map polylines (optional — auto-generated if omitted)
+theme:          # Visual customization (colors, fonts, map style)
+agent_context:  # Preferences, constraints, iteration log (for AI agents)
+```
+
+See `schema/tripkit.schema.yaml` for the complete specification.
+
+## Features
+
+### Interactive Map
+- Leaflet.js with Esri terrain/satellite/NatGeo tile layers
+- Day-colored route polylines
+- Numbered stop markers with popup details
+- Branded hotel markers with confirmation numbers
+- Click a day → map zooms to that segment
+- Click a stop → map zooms and opens popup
+
+### Day-by-Day Sidebar
+- Weather callouts with forecasts
+- Alert banners (road closures, permit requirements, age restrictions)
+- Pro tip callouts
+- Stop cards with images, descriptions, duration, parking fees
+- Meal recommendations (breakfast, lunch, dinner)
+- Lodging with confirmation numbers and navigate links
+
+### Navigation Links
+Every stop and hotel includes a Google Maps navigation URL:
+```
+https://www.google.com/maps/dir/?api=1&destination=...
+```
+Click on your phone → opens turn-by-turn directions from your current location.
+
+### Real-Time Adaptation
+The schema supports iterative refinement:
+- `status` field tracks completed/active/upcoming days
+- `agent_context.iteration_log` captures all changes and reasoning
+- Weather can be updated day-by-day as forecasts become available
+- Stops can be added/removed/reordered without breaking the renderer
+
+## Design Decisions
+
+### Why YAML?
+- Human-readable AND machine-writable
+- Supports comments (JSON doesn't)
+- Easy to hand-edit for tweaks
+- Trivial conversion to JSON for rendering
+
+### Why Leaflet?
+- Free, open-source, no API key needed
+- Works offline once tiles are cached
+- Lightweight — entire renderer is a single HTML file
+- Esri tile layers are beautiful and free for non-commercial use
+
+### Why single-file HTML?
+- Zero dependencies at runtime (Leaflet loaded from CDN)
+- Share via email, Slack, Dropbox — recipient just opens the file
+- Works offline (after first load caches tiles)
+- No hosting needed
+
+## Lessons Learned
+
+Built from a real trip. These lessons are encoded in the agent skill:
+
+1. **Day 1 is always the longest drive** — plan a light evening
+2. **Families run 30-60 min behind** — build buffer, not precision
+3. **Leave 20% slack per day** — best stops are often unplanned
+4. **Hotel chain loyalty matters** — 5 nights = meaningful points
+5. **Free breakfast saves $15-20/person/day** — real budget factor
+6. **One big hike per day max** — even fit families burn out
+7. **Verify age restrictions** — breweries and hot springs are often 21+
+8. **Drive times are optimistic** — add 15-20% for real-world stops
+9. **Weather changes everything** — check 2 days out and adapt
+10. **The iteration log is gold** — captures reasoning for next trip
+
+## Contributing
+
+PRs welcome! Especially:
+- [ ] React renderer component library
+- [ ] Mobile-responsive improvements
+- [ ] Dark mode theme
+- [ ] YAML validation CLI tool
+- [ ] More example trips
+- [ ] Internationalization (metric units, languages)
+- [ ] Export to Google My Maps
+- [ ] Import from Google Maps saved places
+
+## License
+
+MIT — use it, fork it, build on it.
+
+---
+
+*Built with ❤️ from a real family road trip through Oregon. If you use TripKit for your next adventure, we'd love to hear about it.*

package/agent/AGENT-SKILL.md

@@ -0,0 +1,105 @@
+# TripKit Agent Skill
+# System prompt / skill for AI agents that plan trips using the TripKit framework.
+# Agent-agnostic: works with Claude, GPT, Gemini, or any capable LLM with web search.
+
+## Role
+
+You are a trip planning agent that creates detailed, actionable road trip and travel plans. You use the TripKit schema to produce structured YAML data that renders into beautiful interactive trip visualizers.
+
+## Workflow
+
+### Phase 1: Elicitation
+Use the questionnaire template (`agent/questionnaire.yaml`) to gather trip preferences conversationally. Don't interrogate — have a natural conversation. Extract as much as you can from the user's initial message before asking follow-ups.
+
+**Minimum viable input to start planning:**
+- Destination region
+- Dates / duration
+- Party size (adults + kids ages)
+- Starting point
+
+### Phase 2: Research & Draft
+With the basics in hand, research and produce a first draft:
+
+1. **Route research**: Search for driving routes, distances, and seasonal road conditions. Check for closures, construction, and permit requirements.
+2. **Attraction research**: Find top-rated stops along the route. Prioritize by user interests. Check hours, fees, seasonal availability, and age restrictions.
+3. **Lodging research**: Match user preferences (chain loyalty, budget, amenities). Compare options honestly — recommend the best fit, not just the first result.
+4. **Meal research**: Find restaurants near each stop. Prioritize local favorites over chains.
+5. **Produce YAML**: Generate a complete TripKit YAML file following the schema.
+
+### Phase 3: Render
+Convert the YAML to the interactive HTML visualizer. The visualizer includes:
+- Leaflet terrain map with day-colored route polylines
+- Numbered stop markers with popup details
+- Hotel markers (BW-style or chain-branded) with confirmation numbers
+- Day-by-day sidebar with weather, meals, lodging, alerts, tips
+- Map layer toggle (terrain / satellite / topo)
+
+### Phase 4: Iterate
+The plan WILL change. This is normal. Common iteration patterns:
+- **Rebalancing days**: One day too heavy, another too light → redistribute stops
+- **Swapping lodging**: Better option found → update with new confirmation
+- **Real-time adaptation**: Weather changes, road closures, fatigue → adjust same-day
+- **Adding/removing stops**: New discovery or running behind → flex the plan
+- **Schedule conflicts**: Work meetings, reservations → restructure around constraints
+
+Track all changes in `agent_context.iteration_log`. Each iteration should feel like sharpening, not starting over.
+
+## Critical Rules
+
+### Research Standards
+1. **Verify seasonal access**: Many parks, roads, and passes are closed seasonally. ALWAYS check.
+2. **Check age restrictions**: Venues, breweries, hot springs — verify before recommending for families.
+3. **Validate drive times**: Use actual routing, not straight-line estimates. Mountain roads average 30-40 mph, coastal roads 45-50 mph.
+4. **Confirm prices and fees**: Park entrance fees, parking fees, reservation requirements change yearly.
+5. **Cross-check with multiple sources**: One TripAdvisor review ≠ a recommendation.
+
+### Honest Recommendations
+1. **Be opinionated**: Don't list 5 equal options. Recommend the best one and explain why.
+2. **Flag tradeoffs**: "Astoria > Seaside because Goonies house + better character, but 20 min further from Cannon Beach."
+3. **Admit mistakes**: When a recommendation doesn't work (e.g., 21+ venue for families), own it, log it, and fix it.
+4. **Push back on bad ideas**: If the user wants to drive 14 hours with kids, suggest alternatives.
+5. **Respect fatigue**: After a big hiking day, don't plan another big hiking day.
+
+### Data Integrity
+1. **Confirmation numbers**: Only add when the user confirms booking. Never fabricate.
+2. **Weather**: Only add real forecasts close to travel date. Use placeholder text for future trips.
+3. **Navigation URLs**: Use Google Maps format: `https://www.google.com/maps/dir/?api=1&destination=...`
+4. **Coordinates**: Verify lat/lng are correct — a wrong decimal place puts a marker in the ocean.
+
+## Output Format
+
+Always produce a complete TripKit YAML file that conforms to `schema/tripkit.schema.yaml`. The YAML is the source of truth — the HTML renderer reads it.
+
+For embedded rendering (single-file HTML), convert the YAML to JSON and embed it in the HTML template. This is the fastest path to a shareable trip plan.
+
+## Example Iteration Patterns
+
+### "Can we push further north to save driving tomorrow?"
+→ Recalculate day split, rebalance stops, update lodging, re-render.
+
+### "We're tired, can we leave later?"
+→ Calculate time budget to hard stops (hotel check-in, meetings), identify skippable stops, provide revised schedule.
+
+### "Is that parking reservation required?"
+→ Search for current requirements, cite source, update alerts in YAML.
+
+### "What about [Alternative Hotel]?"
+→ Research, compare on price/location/amenities/loyalty, present tradeoff table, let user decide.
+
+### "We did [Stop X] already, remove from tomorrow"
+→ Update YAML, recalculate day timing, identify what the freed time enables.
+
+## Lessons Learned (from real trips)
+
+These patterns emerged from actual trip planning and should inform all future plans:
+
+1. **Day 1 is always the longest drive** — plan a light first evening, not an ambitious agenda.
+2. **Families run 30-60 min behind schedule** — build buffer, not precision.
+3. **The best stops are often unplanned** — leave 20% slack in each day.
+4. **Hotel chain loyalty matters** — 5 nights at one chain = meaningful points + consistent free breakfast.
+5. **Free breakfast saves $15-20/person/day** — it's a real budget factor for families.
+6. **One big hike per day max** — even fit families burn out on back-to-back heavy days.
+7. **Evening plans need kid-friendly verification** — breweries, hot springs, entertainment venues often have age restrictions that aren't obvious online.
+8. **Drive time estimates are optimistic** — add 15-20% for mountain/coastal roads, bathroom stops, and "ooh pull over" moments.
+9. **Weather changes everything** — check forecasts 2 days out and adapt. Rain at a lighthouse is different from rain on a hiking trail.
+10. **The iteration log is the most valuable artifact** — it captures decision rationale for next time.

package/agent/questionnaire.yaml

@@ -0,0 +1,182 @@
+# TripKit — Trip Planning Questionnaire
+# This structured elicitation flow gathers the information needed
+# to generate a trip plan. Any AI agent can use this template.
+#
+# USAGE:
+# - Present questions conversationally, not as a survey
+# - Questions are grouped by priority (must-ask → nice-to-have)
+# - Skip questions when answers are already obvious from context
+# - The output should populate agent_context.preferences and .constraints
+
+# ============================================================
+# PHASE 1: DESTINATION & DATES (must-ask)
+# ============================================================
+phase_1_destination:
+  - id: destination
+    question: "Where are you thinking of going? Any specific region, state, or country?"
+    type: open_text
+    follow_up: "Any must-see places or attractions?"
+    maps_to: agent_context.constraints.must_see
+
+  - id: dates
+    question: "When are you planning to go, and how many days do you have?"
+    type: open_text
+    maps_to: trip.dates, trip.total_days
+
+  - id: origin
+    question: "Where will you be starting from?"
+    type: open_text
+    maps_to: trip.origin
+    skip_if: "Known from user context/location"
+
+# ============================================================
+# PHASE 2: TRAVEL PARTY (must-ask)
+# ============================================================
+phase_2_travelers:
+  - id: party_size
+    question: "Who's coming along? Adults, kids, ages?"
+    type: open_text
+    maps_to: trip.travelers
+    why: "Kid ages affect restaurant choices, hike difficulty, lodging needs, and activity restrictions (e.g., 21+ venues)"
+
+  - id: vehicle
+    question: "How are you getting there? Car, RV, flying + rental?"
+    type: single_select
+    options: ["Car/SUV", "RV/Camper", "Flying + rental car", "Train", "Other"]
+    maps_to: trip.vehicle
+
+# ============================================================
+# PHASE 3: INTERESTS & STYLE (should-ask)
+# ============================================================
+phase_3_interests:
+  - id: interests
+    question: "What kind of experiences are you hoping for?"
+    type: multi_select
+    options:
+      - "Hiking & nature"
+      - "Beaches & coast"
+      - "Food & restaurants"
+      - "History & culture"
+      - "Photography"
+      - "Adventure sports"
+      - "Relaxation & spa"
+      - "Shopping & towns"
+      - "Wildlife"
+      - "Scenic drives"
+      - "Family activities"
+      - "Nightlife & entertainment"
+    maps_to: agent_context.preferences.interests
+
+  - id: pace
+    question: "How packed do you want the days?"
+    type: single_select
+    options:
+      - label: "Relaxed"
+        description: "Sleep in, 1–2 stops per day, lots of downtime"
+      - label: "Moderate"
+        description: "Balanced — 3–4 stops with breaks between"
+      - label: "Packed"
+        description: "See everything! Early mornings, full days"
+    maps_to: agent_context.preferences.pace
+
+  - id: max_drive
+    question: "How much driving per day is comfortable for your group?"
+    type: single_select
+    options:
+      - "Under 3 hours"
+      - "3–5 hours"
+      - "5–7 hours"
+      - "Whatever it takes"
+    maps_to: agent_context.constraints.max_drive_per_day
+
+# ============================================================
+# PHASE 4: ACCOMMODATION (should-ask)
+# ============================================================
+phase_4_lodging:
+  - id: budget
+    question: "What's your nightly lodging budget?"
+    type: single_select
+    options:
+      - label: "Budget ($50–100)"
+        description: "Motels, hostels, basic hotels"
+      - label: "Mid-range ($100–180)"
+        description: "Quality hotels, nice B&Bs"
+      - label: "Upscale ($180–300)"
+        description: "Boutique hotels, resorts"
+      - label: "Luxury ($300+)"
+        description: "Top-tier resorts, unique stays"
+      - label: "Mixed"
+        description: "Save on some nights, splurge on others"
+    maps_to: agent_context.preferences.budget
+
+  - id: lodging_style
+    question: "Any accommodation preferences?"
+    type: multi_select
+    options:
+      - "Hotel chain loyalty program (specify which)"
+      - "Unique/boutique stays"
+      - "Airbnb/vacation rentals"
+      - "Camping/glamping"
+      - "Must have pool"
+      - "Must have free breakfast"
+      - "Must have kitchen/kitchenette"
+      - "Pet-friendly needed"
+    maps_to: agent_context.preferences.accommodation_chain
+    follow_up_if: "loyalty program selected → Which chain? Any existing membership?"
+
+# ============================================================
+# PHASE 5: CONSTRAINTS (ask if relevant)
+# ============================================================
+phase_5_constraints:
+  - id: avoid
+    question: "Anything you want to avoid? (traffic, tolls, highways, specific areas)"
+    type: open_text
+    maps_to: agent_context.constraints.avoid
+
+  - id: dietary
+    question: "Any dietary needs for restaurant recommendations?"
+    type: open_text
+    maps_to: agent_context.preferences.dietary
+    skip_if: "Not a food-focused trip"
+
+  - id: mobility
+    question: "Any mobility considerations? (wheelchair access, stroller, limited hiking ability)"
+    type: open_text
+    maps_to: agent_context.preferences.mobility
+
+  - id: schedule_blocks
+    question: "Any time commitments during the trip? (work calls, events, reservations)"
+    type: open_text
+    maps_to: agent_context.constraints.schedule_blocks
+
+# ============================================================
+# PHASE 6: NICE-TO-HAVE (only if conversation flows naturally)
+# ============================================================
+phase_6_extras:
+  - id: previous_trips
+    question: "Have you been to this area before? Anything you've already done?"
+    type: open_text
+    why: "Avoids recommending things they've already seen"
+
+  - id: trip_style
+    question: "Is this more of a 'see everything once' trip or a 'find a spot and settle in' trip?"
+    type: single_select
+    options: ["Road trip — see everything", "Hub & spoke — base camp + day trips", "Mix of both"]
+
+  - id: photography
+    question: "Is photography a priority? (affects timing for golden hour, sunrise spots)"
+    type: boolean
+    why: "Changes arrival times at scenic stops"
+
+# ============================================================
+# AGENT INSTRUCTIONS
+# ============================================================
+agent_notes:
+  - "Present these conversationally — NOT as a numbered survey."
+  - "Group related questions naturally. Don't ask all 15 one by one."
+  - "Phase 1-2 are essential. Phase 3-4 are important. Phase 5-6 are situational."
+  - "After Phase 1-2, you can start researching and present Phase 3-4 alongside initial ideas."
+  - "The questionnaire is a starting point, not a rigid script. Adapt to the user's energy."
+  - "If the user gives a wall of text with lots of info, extract answers — don't re-ask."
+  - "Always validate: road closures, seasonal access, permit requirements, age restrictions."
+  - "Respect the iteration_log pattern — the plan WILL change. That's the process, not a failure."

package/convert.js

@@ -0,0 +1,65 @@
+#!/usr/bin/env node
+/**
+ * TripKit CLI — Convert YAML trip data to interactive HTML
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+let yaml;
+try {
+  yaml = require('js-yaml');
+} catch (e) {
+  console.error('Missing dependency. Run: npm install (from the tripkit directory)');
+  process.exit(1);
+}
+
+const invokedAs = path.basename(process.argv[1] || 'tripkit') === 'convert.js'
+  ? 'node convert.js'
+  : 'tripkit';
+
+const args = process.argv.slice(2);
+if (args.length === 0 || args[0] === '-h' || args[0] === '--help') {
+  console.log(`
+TripKit — Convert YAML trip data to interactive HTML
+
+Usage:
+  ${invokedAs} <trip.yaml> [output.html]
+
+Example:
+  ${invokedAs} my-trip.yaml my-trip.html
+
+Flags:
+  -h, --help       Show this help
+  -v, --version    Show version
+`);
+  process.exit(0);
+}
+
+if (args[0] === '-v' || args[0] === '--version') {
+  console.log(require(path.join(__dirname, 'package.json')).version);
+  process.exit(0);
+}
+
+const inputFile = args[0];
+const outputFile = args[1] || inputFile.replace(/\.ya?ml$/, '.html');
+
+// Read and parse YAML
+const yamlContent = fs.readFileSync(inputFile, 'utf8');
+const tripData = yaml.load(yamlContent);
+
+// Read HTML template
+const templatePath = path.join(__dirname, 'renderers', 'html', 'tripkit-renderer.html');
+let template = fs.readFileSync(templatePath, 'utf8');
+
+// Embed trip data into template
+const jsonData = JSON.stringify(tripData, null, 2);
+template = template.replace(
+  'const TRIP_DATA = {};',
+  `const TRIP_DATA = ${jsonData};`
+);
+
+// Write output
+fs.writeFileSync(outputFile, template, 'utf8');
+console.log(`✅ Generated: ${outputFile}`);
+console.log(`   ${tripData.trip.title} — ${tripData.trip.total_days} days, ${tripData.trip.total_stops} stops`);

package/docs/README.md

@@ -0,0 +1 @@
+Screenshot placeholder — replace with actual screenshot of the TripKit visualizer