tripkit 1.1.0 → 1.4.0

package/CHANGELOG.md

@@ -2,15 +2,58 @@
 
 All notable changes to TripKit are documented here. Versioning follows [SemVer](https://semver.org/).
 
-## [1.1.0] — 2026-04-30
+## [1.4.0] — 2026-06-27
 
 ### Added
-- **`tripkit validate <trip.yaml>`** — schema validator that checks required fields, lat/lng ranges, valid stop types, hex colors, day numbering (sequential, status enum), `trip.total_days` / `trip.total_stops` consistency, optional routes structure, and theme fields. Warnings are advisory; errors block render.
-- Pre-render validation is now automatic. Pass `--no-validate` to bypass.
-- Mobile polish at iPhone widths (≤480px): collapsible map legend (tap to expand), tighter day-nav, smaller hero, repositioned map controls. No regression at desktop or tablet sizes.
+- **Post-trip media — interactive map mode.** Attach a trip's real geotagged photos/videos to stops and see them on the map.
+  - **`tripkit media <folder> <trip.yaml>`** — scans a media folder, reads EXIF GPS + timestamps (`exifr`), auto-matches each item to the nearest stop on the matching day (haversine, day-gated by photo date), optionally generates thumbnails (`sharp`, optional dependency — gracefully skipped if absent), and writes a `<trip>.media-review.yaml` handoff file. Low-confidence / geotag-less / too-far items go to an `unmatched:` bucket for review.
+  - **`tripkit media apply <review.yaml> <trip.yaml>`** — merges the reviewed/captioned media into `stops[].media[]`. Idempotent.
+  - **Schema:** new optional `stops[].media[]` (also valid on `lodging`): `{ src, type: photo|video, thumb?, caption?, lat?, lng?, taken_at? }`. `src` is a relative path **or** a URL, so output can stay a shareable single file. Purely additive — stops without media render exactly as before.
+  - **Renderer:** stop cards and map popups show a thumbnail strip + a `📷 N` count badge; **stop markers with media get a corner `📷 N` badge that opens the lightbox directly** (the marker body still opens the normal popup); a full-screen **lightbox** (keyboard ←/→/Esc, click, swipe; inline video playback) opens from any thumbnail; a toggleable **photo-pin map layer** plots every media item that carries its own EXIF GPS, distinct from the day-numbered stop markers.
+  - **Validation:** `tripkit validate` checks each media item has a `src` and valid `type`, and warns when a media item's GPS is >25 mi from its stop (likely a wrong match).
+  - **Agent skill:** new Phase 5 documents the post-trip ingest → review → apply flow, with the agent owning the captioning/match-fixing review step.
+  - **Guide:** `docs/MEDIA-GUIDE.md` — end-to-end walkthrough (CLI steps, the review-file format field by field, AI-agent orchestration, the `media` schema, URLs vs local files, troubleshooting, command reference). Linked from the README and the agent skill.
+- Dependencies: `exifr` (required for ingest) added to `dependencies`; `sharp` (thumbnails) added to `optionalDependencies`.
 
 ### Fixed
-- CSS cascade bug: previous mobile media query was placed before base `.legend` rules, so overrides silently lost the cascade. Moved to end of stylesheet where it belongs.
+- **Lightbox close button.** The full-width photo counter (`1 / 2`) overlay was intercepting clicks aimed at the `×` button, so closing by click failed (Esc still worked). The counter is now click-through and the close button sits above it.
+- **Origin/destination pins now connect to the route.** Auto-generated polylines (no explicit `routes[]`) now anchor Day 1 to `trip.origin` and the final day back to the destination (or origin, for a round trip). Previously the green "A" Start pin floated unattached — most visible when the last day's lodging is `name: "Home"` at the origin, which the route generator excludes from geometry.
+
+## [1.3.0] — 2026-04-30
+
+### Added
+- GitHub Actions CI: runs `npm test` (validator + skill-coverage gate) and validates every YAML in `examples/` on Node 18/20/22 for every push and PR to `main`.
+- **Claude Code skill bundle.** `agent/SKILL.md` now ships with `name`/`description` YAML frontmatter so it discovers as a proper Claude Code skill. New `npx tripkit install-skill` command copies the skill to `~/.claude/skills/tripkit/` (or `--project` for `.claude/skills/`); after install, invoke with `/skills tripkit`.
+- **Dark mode.** `theme.dark_mode: true` now applies a `data-theme="dark"` attribute to the document and overrides the full color system: warm near-black background, lifted accent green, translucent callout tints, dark Leaflet popups. Stop badges, callouts, and chrome all theme automatically.
+- **Day-status visual treatment.** The `status: completed | active | upcoming` field on each day is now reflected in the day-nav: completed days are muted, the day flagged `active` (today) gets a small accent dot. Selecting a muted day still highlights it fully.
+
+### Changed
+- Renamed `agent/AGENT-SKILL.md` → `agent/SKILL.md` to match Claude Code's skill convention. The body is unchanged and still agent-agnostic; the new frontmatter is ignored by non-Claude tooling.
+- Renderer color system refactored to CSS variables. Stop badge colors, callout backgrounds, and shadows are all theme-aware via `--b-*-bg/fg`, `--*-soft`, and `--shadow*` variables — single source of truth for both light and dark modes.
+- Stop cards lift on hover (subtle shadow + 1px translate) for a more tactile feel.
+- Removed unused `--coral` variable (was a duplicate of `--warn`).
+
+## [1.2.0] — 2026-04-30
+
+### Added
+- **`tripkit validate <trip.yaml>`** — schema validator that checks required fields, lat/lng ranges, valid stop types, hex colors, day numbering (sequential, status enum), `trip.total_days` / `trip.total_stops` consistency, optional routes structure, and theme fields. Warnings are advisory; errors block render. Pre-render validation is automatic; pass `--no-validate` to bypass. Includes a warning when any consecutive-day jump (Day N's lodging-or-last-stop → Day N+1's first stop) exceeds 250 mi without an explicit `routes[]` entry.
+- **Origin / destination pins.** New optional schema fields `trip.origin_lat`, `trip.origin_lng`, `trip.destination_lat`, `trip.destination_lng`. When set, the renderer draws a green "A" Start pin and (for one-way trips) a red "B" End pin. For round trips, omit the destination fields. Without these, the trip's start/end was previously invisible — polylines just terminated in empty space.
+- `theme.hotel_label` — optional 1–4 char string overriding the auto-derived hotel marker label. Falls back to first 3 chars of `agent_context.preferences.accommodation_chain`, then 🏨.
+- Three new example trips: `southwest-parks-2026.yaml` (5-day UT/AZ parks loop, Zion/Bryce/Page/Grand Canyon), `nyc-long-weekend-2026.yaml` (3-day fly-in city break, single Marriott, no driving — exercises `museum`/`city`/`food`/`shopping`), `new-england-fall-2026.yaml` (5-day VT/NH foliage loop, regional inns, serif theme).
+- Mobile polish at iPhone widths (≤480px): collapsible map legend (tap to expand), tighter day-nav, smaller hero, repositioned map controls. No regression at desktop or tablet.
+- **Skill drift check.** `scripts/check-skill-coverage.js` enumerates 44 renderer-meaningful schema fields and asserts every one is mentioned in `agent/AGENT-SKILL.md`. Wired into `npm test` so future schema additions can't ship without updating the agent skill.
+
+### Fixed
+- **Disjointed inter-day routes.** When auto-generating route polylines (no explicit `routes[]` defined), each day's segment is now anchored to the previous day's lodging at the start and today's lodging at the end. Day N's polyline runs `prev-lodging → stops → today-lodging` and Day N+1 starts from the same point — the trip reads as one continuous chain instead of disconnected per-day segments.
+- Duplicate hotel markers when one hotel covers multiple consecutive nights (visible in NYC's 3-night Marriott stay). Markers are now deduped by lat/lng, popups show "Nights X–Y · {first date} – {last date}", legend count reflects unique hotels.
+- "Full route" bounds now include hotels and origin/destination pins, not just stops. Previously the Vegas start pin on the Southwest trip was off-screen on initial load.
+- CSS cascade bug: mobile media query was placed before base `.legend` rules, so overrides silently lost the cascade. Moved to end of stylesheet.
+
+### Changed
+- Southwest and New England examples ship explicit `routes:` blocks (matching the Oregon pattern). Polylines follow real road geometry (I-15, US-89, Kancamagus Hwy, Rt 100, etc.) instead of relying on auto-generation. NYC stays auto-generated.
+- All four examples now ship `origin_lat`/`origin_lng` (Oregon/Folsom, Southwest/Las Vegas, NYC/JFK, New England/Boston).
+- **Agent skill rewritten** to reflect the validate workflow, `theme.hotel_label`, the `routes[]` convention (when to use vs. when to omit), the lodging-anchor auto-fallback, origin/destination guidance, the 250-mi long-leg warning, and 12 lessons learned (two new from this set of work).
+- CONTRIBUTING: documented the routes convention — road trips should ship explicit `routes:`, city trips can omit.
 
 ## [1.0.1] — 2026-04-30
 

package/README.md

@@ -75,10 +75,31 @@ npx tripkit validate my-trip.yaml
 
 It checks required fields, lat/lng ranges, valid stop types, hex colors, day numbering, and warns when `trip.total_stops` doesn't match the actual count. Validation also runs automatically before each render — pass `--no-validate` to skip it.
 
+### Add your trip photos (after the trip)
+
+Turn a folder of geotagged photos/videos into an interactive map where each stop shows what you actually captured:
+
+```bash
+npx tripkit media ./my-photos my-trip.yaml      # 1. EXIF-match photos to stops → writes my-trip.media-review.yaml
+#    edit captions / fix any mismatches in the review file
+npx tripkit media apply my-trip.media-review.yaml my-trip.yaml   # 2. merge into the trip
+npx tripkit my-trip.yaml my-trip.html           # 3. re-render with galleries
+```
+
+Step 1 reads EXIF GPS + timestamps and auto-matches each photo to the nearest stop on the matching day. Items it can't place confidently (no GPS, too far from any stop) land in an `unmatched:` bucket you can fix by hand — or hand to an AI agent to caption and place. Thumbnails are generated automatically if [`sharp`](https://www.npmjs.com/package/sharp) is installed (optional). In the rendered page, stops gain a photo strip + count badge, a full-screen lightbox (arrow keys / swipe, inline video), and a toggleable map layer pinning every geotagged shot.
+
+`src` values can be relative paths (the default) **or** URLs — use URLs if you want the output to stay a single shareable HTML file.
+
+📖 **Full walkthrough:** [docs/MEDIA-GUIDE.md](docs/MEDIA-GUIDE.md) — the review-file format, how matching works, letting an AI agent caption and place your photos, and troubleshooting.
+
 ### 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
+2. Share the `agent/SKILL.md` as context — or, if you're using **Claude Code**, install it as a skill (one-time):
+   ```bash
+   npx tripkit install-skill          # installs to ~/.claude/skills/tripkit/
+   ```
+   then invoke with `/skills tripkit` in any conversation.
 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
@@ -97,7 +118,10 @@ tripkit/
 ├── schema/
 │   └── tripkit.schema.yaml      # Data contract — the spec
 ├── examples/
-│   └── oregon-spring-2026.yaml  # Complete real-world example
+│   ├── oregon-spring-2026.yaml      # 6-day road trip (reference example)
+│   ├── southwest-parks-2026.yaml    # 5-day UT/AZ national parks loop
+│   ├── nyc-long-weekend-2026.yaml   # 3-day fly-in city break, no car
+│   └── new-england-fall-2026.yaml   # 5-day VT/NH foliage tour
 ├── renderers/
 │   ├── html/
 │   │   └── tripkit-renderer.html  # Self-contained HTML renderer
@@ -105,7 +129,7 @@ tripkit/
 │       └── (coming soon)          # React component library
 ├── agent/
 │   ├── questionnaire.yaml       # Elicitation template
-│   └── AGENT-SKILL.md           # System prompt for AI agents
+│   └── SKILL.md                 # System prompt + Claude Code skill bundle
 ├── docs/
 │   └── screenshot.png
 ├── convert.js                   # YAML → HTML CLI tool
@@ -149,6 +173,13 @@ See `schema/tripkit.schema.yaml` for the complete specification.
 - Click a day → map zooms to that segment
 - Click a stop → map zooms and opens popup
 
+### Trip Photos & Videos
+- `tripkit media` ingests a folder of geotagged photos/videos and EXIF-matches them to stops
+- Per-stop photo strip + count badge in cards and map popups
+- Full-screen lightbox: arrow keys / swipe to navigate, inline video playback
+- Toggleable map layer that pins every geotagged shot at its own location
+- Photos stay as relative paths or URLs — the output can still be a single shareable file
+
 ### Day-by-Day Sidebar
 - Weather callouts with forecasts
 - Alert banners (road closures, permit requirements, age restrictions)

package/agent/SKILL.md

@@ -0,0 +1,168 @@
+---
+name: tripkit
+description: Plan road trips and itineraries that render as interactive map visualizations. Produces YAML conforming to the TripKit schema, validates it with `tripkit validate`, and renders to a self-contained HTML file via `npx tripkit`.
+---
+
+# TripKit Agent Skill
+
+System prompt / skill for AI agents that plan trips using the TripKit framework. The YAML frontmatter above is for Claude Code's `/skills` discovery; the body itself is 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 produce structured YAML conforming to `schema/tripkit.schema.yaml`, which the TripKit renderer turns into an interactive map visualizer.
+
+## Workflow
+
+### Phase 1: Elicitation
+Use `agent/questionnaire.yaml` to gather trip preferences conversationally. Don't interrogate — 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 (city + ideally lat/lng — see `trip.origin_lat/lng` below)
+
+### Phase 2: Research & Draft
+1. **Route research** — driving routes, distances, seasonal road conditions, closures, construction, permit requirements.
+2. **Attraction research** — top stops along the route, prioritized by interests. Verify hours, fees, age restrictions.
+3. **Lodging research** — match user's chain loyalty / budget / amenities. Be opinionated.
+4. **Meal research** — local favorites near each stop.
+5. **Generate the YAML** — full TripKit document (see Schema Reference below).
+6. **Validate before render** — run `tripkit validate <trip>.yaml`. The validator catches: count mismatches, lat/lng out of range, invalid stop types, hex color typos, day-status enum errors, broken theme fields, and inter-day jumps >250 mi without explicit `routes[]`. Errors block render; warnings are advisory.
+
+### Phase 3: Render
+- `npx tripkit <trip>.yaml <out>.html` (auto-runs validation; pass `--no-validate` to skip).
+- Output is a single self-contained HTML file with a Leaflet map, day-by-day sidebar, and inline CSS/JS.
+
+### Phase 4: Iterate
+The plan WILL change. Track every change in `agent_context.iteration_log` with date + reasoning. Common patterns:
+- **Rebalance days** — redistribute stops when one day is heavy and another is light.
+- **Swap lodging** — better option found, update with new confirmation.
+- **Real-time adaptation** — weather changes, road closures, fatigue.
+- **Schedule conflicts** — work meetings, reservations.
+
+### Phase 5: Post-trip media (optional)
+After the trip, the traveler can attach their real geotagged photos/videos to stops so the map shows what they actually saw. This is a **review-in-the-middle** flow — your job is the "review" step:
+
+1. **Build** — the user runs `tripkit media <media-folder> <trip>.yaml`. This reads EXIF GPS + timestamps, auto-matches each item to the nearest stop on the matching day (haversine), generates thumbnails if `sharp` is installed, and writes `<trip>.media-review.yaml`. Items with no GPS, no stops on the day, or a nearest stop too far away land in an `unmatched:` bucket.
+2. **Review (your role)** — open the review file. For each item: write a short, specific `caption` (what it shows, not "photo 1"). Fix any mis-matched `stop_index`. For `unmatched` items, reason from the filename, `taken_at`, and the trip plan to assign a `day` + `stop_index` — or leave them unmatched if genuinely unplaceable. Use the `suggested_stop`/`reason` hints.
+3. **Apply** — the user runs `tripkit media apply <trip>.media-review.yaml <trip>.yaml` to merge the reviewed items into `stops[].media[]`, then re-renders. Apply is idempotent (re-running won't duplicate).
+
+Captions are the high-value artifact here — they're what the lightbox shows. Keep them concise and grounded in what's actually visible.
+
+Full reference (review-file format, matching rules, edge cases): `docs/MEDIA-GUIDE.md`.
+
+## Schema Reference (must match `schema/tripkit.schema.yaml`)
+
+### `trip` block
+- `title`, `subtitle`, `dates`, `total_days`, `total_miles`, `total_stops`
+- `travelers: { adults, children, ages }`
+- `origin: string` — human-readable origin (e.g. "Folsom, CA").
+- `origin_lat`, `origin_lng` — **always include if known**. Renders a green "A" Start pin on the map. Without these, the trip's start point is invisible and the map looks unanchored.
+- `destination_lat`, `destination_lng` — only set if the trip ends somewhere different from origin (one-way trips). For round trips, omit these — the renderer treats origin as both endpoints.
+- `vehicle` — "SUV" / "Sedan" / "Rental SUV" / "Subway + walking" / "RV" / "Train".
+
+### `days[]` block
+Each day:
+- `number` — must be sequential starting at 1 (validator warns otherwise).
+- `title`, `date`, `status` (`completed` | `active` | `upcoming`)
+- `color` — hex (`#abc` or `#aabbcc`); used for the day's polyline and marker.
+- `summary: { drive, hike, miles }` — strings, can be `"—"` for non-applicable.
+- `weather: { high, low, sky, rain_chance, note }` — only include if forecast is real (within 10 days). Otherwise omit.
+- `meals: { breakfast, lunch, dinner, snack? }`
+- `lodging: { name, location, price_estimate, confirmation, booked, lat, lng, notes, navigate_url }` — `lat`/`lng` is **required** for the hotel marker to render. Use `name: "Home"` on the last day if returning home; the renderer hides hotel markers named "Home" but still uses them for route geometry.
+- `alerts: [string]` — warnings (closures, age limits, permits).
+- `tips: [string]` — pro tips from research.
+- `stops: [...]` — see below.
+
+### `stops[]` block
+- `name`, `lat`, `lng` — **lat/lng required**. Out-of-range values fail validation.
+- `type` — one of `hike | scenic | food | city | activity | beach | museum | shopping`. Validator rejects others.
+- `label` — short display text in the badge ("Hike", "Sunset", "Lunch", "Detour", "Photo stop").
+- `description` — 2–3 sentences with insider context. The badge says what kind, the description says why and how.
+- `duration`, `parking_fee`, `hours`, `accessibility` — optional strings.
+- `kid_friendly: bool` — set `false` to surface a "⚠ Not kid-friendly" badge.
+- `reservation_required: bool` + `reservation_url` — for permit/timed-entry stops.
+- `image` — Unsplash or other URL. If omitted, the renderer falls back to a type-specific default.
+- `navigate_url` — Google Maps directions link.
+- `media: [...]` — **post-trip only.** A gallery of the traveler's actual photos/videos at this stop. Usually populated by the `tripkit media` ingest flow (see Phase 5), not hand-authored during planning. Each item: `{ src, type: photo|video, thumb?, caption?, lat?, lng?, taken_at? }`. `src` is a relative path or URL. Items with `lat`/`lng` also drive the renderer's toggleable photo-pin map layer.
+
+### `routes[]` block (optional but strongly recommended for road trips)
+Each entry:
+- `day` — which day (must reference a real day number).
+- `color`, `width` — visual.
+- `points: [[lat, lng], ...]` — polyline waypoints. Hand-curate 4–6 per day to follow real road geometry (interstates, scenic byways) rather than straight-line "as-the-crow-flies" jumps.
+
+**When to include `routes[]`:**
+- Road trips with significant driving between regions: **yes**, always. See `examples/oregon-spring-2026.yaml`, `southwest-parks-2026.yaml`, `new-england-fall-2026.yaml`.
+- City trips with no driving (subway / walking): **no**, omit. The auto-fallback handles dense urban stops fine. See `examples/nyc-long-weekend-2026.yaml`.
+
+**Auto-fallback behavior** (when `routes[]` is omitted): the renderer auto-generates per-day polylines as `previous-day's-lodging → today's stops → today's-lodging`, which provides reasonable inter-day continuity but produces straight lines between waypoints.
+
+### `theme` block (all optional)
+- `font_family`, `accent_color` (hex)
+- `map_style` — `terrain | satellite | topo | street`
+- `dark_mode: bool`
+- `hotel_label` — 1–4 char string overriding the auto-derived hotel marker label. Use this when the trip uses a non-Best-Western chain or no chain at all (e.g., `"MAR"` for Marriott, `"INN"` for boutique inns). Auto-fallback: first 3 chars of `agent_context.preferences.accommodation_chain`, then 🏨 emoji.
+
+### `agent_context` block (not rendered, preserved for next iteration)
+- `preferences: { pace, budget, accommodation_chain, interests[], dietary, mobility }`
+- `constraints: { max_drive_per_day, must_see[], avoid[], schedule_blocks[] }`
+- `iteration_log: [{ date, change }]` — append-only audit trail. Every meaningful plan change should land here.
+
+## Critical Rules
+
+### Research Standards
+1. **Verify seasonal access** — many parks, roads, passes are closed seasonally. Always check.
+2. **Check age restrictions** — breweries, hot springs, casinos. Verify before recommending for families.
+3. **Validate drive times** — actual routing, not straight-line. Mountain roads ~30–40 mph, coastal ~45–50 mph.
+4. **Confirm prices and fees** — they change yearly.
+5. **Cross-check sources** — one TripAdvisor review ≠ a recommendation.
+
+### Honest Recommendations
+1. **Be opinionated** — recommend the best option, 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 fails (21+ venue for families), own it, log it, fix it.
+4. **Push back on bad ideas** — 14-hour drive day 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 when the user confirms booking. Never fabricate. Use `XXXXX1234` format for example/anonymized data.
+2. **Weather** — only add real forecasts within 10 days of travel. Otherwise omit the `weather:` block.
+3. **Navigation URLs** — Google Maps format: `https://www.google.com/maps/dir/?api=1&destination=...`
+4. **Coordinates** — verify lat/lng before committing. A wrong decimal puts a marker in the ocean. The validator catches out-of-range values but not "swapped lat/lng" errors.
+5. **`trip.total_stops` and `trip.total_days`** — the validator cross-checks these against actual counts. Update both when adding/removing stops.
+
+## Output Format
+
+Produce a complete TripKit YAML file. Then:
+
+```bash
+npx tripkit validate trip.yaml   # confirm clean
+npx tripkit trip.yaml trip.html  # render
+```
+
+Or `node convert.js` from a clone.
+
+## Example Iteration Patterns
+
+- "Can we push further north tomorrow?" → recalculate split, rebalance stops, update lodging, re-render.
+- "We're tired, can we leave later?" → time budget to hard stops, identify skippables, revised schedule.
+- "Is the parking reservation required?" → search current requirements, cite source, update `alerts[]`.
+- "What about [Alternative Hotel]?" → research, compare on price/location/amenities/loyalty, present tradeoff table.
+- "We did [Stop X] already, drop it" → update YAML, recalculate timing, surface what the freed time enables.
+
+## Lessons Learned (from real trips)
+
+1. **Day 1 is always the longest drive** — plan a light first evening.
+2. **Families run 30–60 min behind schedule** — build buffer, not precision.
+3. **The best stops are often unplanned** — leave 20% slack per day.
+4. **Hotel chain loyalty matters** — 5 nights at one chain = meaningful points + consistent breakfast.
+5. **Free breakfast saves $15–20/person/day** — real budget factor.
+6. **One big hike per day max** — even fit families burn out.
+7. **Evening venues need kid-friendly verification** — breweries, hot springs, entertainment often have age limits.
+8. **Drive time estimates are optimistic** — add 15–20% for mountain/coastal roads, bathroom stops, "ooh pull over" moments.
+9. **Weather changes everything** — check 2 days out and adapt.
+10. **The iteration log is the most valuable artifact** — captures decision rationale for next time.
+11. **Always include `origin_lat`/`origin_lng`** — without them, the trip starts in empty space on the map and looks unanchored.
+12. **Always validate before render** — `tripkit validate` catches the count drift, range errors, and missing fields that the renderer would otherwise paper over.

package/convert.js

@@ -29,6 +29,13 @@ TripKit — AI-friendly trip planning toolkit
 Usage:
   ${invokedAs} <trip.yaml> [output.html]    Render YAML to interactive HTML
   ${invokedAs} validate <trip.yaml>         Check a trip YAML for schema errors
+  ${invokedAs} media <folder> <trip.yaml>   Geo-match a folder of trip photos/videos to
+                                            stops and write <trip>.media-review.yaml
+  ${invokedAs} media apply <review.yaml> <trip.yaml>
+                                            Merge a reviewed media file into the trip YAML
+  ${invokedAs} install-skill [--project]    Install the agent skill for Claude Code
+                                            (default: ~/.claude/skills/tripkit/;
+                                             --project: ./.claude/skills/tripkit/)
 
 Flags:
   -h, --help       Show this help
@@ -76,6 +83,23 @@ function reportFindings(errors, warnings) {
   });
 }
 
+// === SUBCOMMAND: install-skill ===
+if (args[0] === 'install-skill') {
+  const projectScope = args.includes('--project');
+  const dest = projectScope
+    ? path.join(process.cwd(), '.claude', 'skills', 'tripkit')
+    : path.join(require('os').homedir(), '.claude', 'skills', 'tripkit');
+  const src = path.join(__dirname, 'agent');
+
+  fs.mkdirSync(dest, { recursive: true });
+  for (const f of fs.readdirSync(src)) {
+    fs.copyFileSync(path.join(src, f), path.join(dest, f));
+  }
+  console.log(c.green('✓') + ` Installed TripKit skill to ${dest}`);
+  console.log(c.dim(`  Invoke in Claude Code with: /skills tripkit`));
+  process.exit(0);
+}
+
 // === SUBCOMMAND: validate ===
 if (args[0] === 'validate') {
   const inputFile = args[1];
@@ -96,6 +120,45 @@ if (args[0] === 'validate') {
   process.exit(errors.length > 0 ? 1 : 0);
 }
 
+// === SUBCOMMAND: media (ingest geotagged photos/videos) ===
+if (args[0] === 'media') {
+  const io = {
+    log: (m) => console.log(m),
+    warn: (m) => console.error(`  ${c.yellow('⚠')} ${m}`),
+    c,
+  };
+  const { buildReview, applyReview } = require('./media-ingest');
+
+  (async () => {
+    try {
+      if (args[1] === 'apply') {
+        const reviewFile = args[2];
+        const tripFile = args[3];
+        if (!reviewFile || !tripFile) {
+          console.error(c.red('Usage: ') + `${invokedAs} media apply <review.yaml> <trip.yaml>`);
+          process.exit(1);
+        }
+        if (!fs.existsSync(reviewFile)) { console.error(c.red(`Error: file not found: ${reviewFile}`)); process.exit(1); }
+        if (!fs.existsSync(tripFile)) { console.error(c.red(`Error: file not found: ${tripFile}`)); process.exit(1); }
+        await applyReview(reviewFile, tripFile, io);
+      } else {
+        const folder = args[1];
+        const tripFile = args[2];
+        if (!folder || !tripFile) {
+          console.error(c.red('Usage: ') + `${invokedAs} media <folder> <trip.yaml>`);
+          process.exit(1);
+        }
+        if (!fs.existsSync(tripFile)) { console.error(c.red(`Error: file not found: ${tripFile}`)); process.exit(1); }
+        await buildReview(folder, tripFile, io);
+      }
+    } catch (e) {
+      console.error(c.red('✖ ') + e.message);
+      process.exit(1);
+    }
+  })();
+  return;
+}
+
 // === DEFAULT: render ===
 const skipValidate = args.includes('--no-validate');
 const positional = args.filter(a => !a.startsWith('-'));