tripkit 1.2.0 → 1.4.0

package/CHANGELOG.md

@@ -2,6 +2,37 @@
 
 All notable changes to TripKit are documented here. Versioning follows [SemVer](https://semver.org/).
 
+## [1.4.0] — 2026-06-27
+
+### Added
+- **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
+- **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

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
@@ -108,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
@@ -152,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/{AGENT-SKILL.md → SKILL.md}

@@ -1,6 +1,11 @@
+---
+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. Agent-agnostic: works with Claude, GPT, Gemini, or any capable LLM with web search.
+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
 
@@ -36,6 +41,17 @@ The plan WILL change. Track every change in `agent_context.iteration_log` with d
 - **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
@@ -69,6 +85,7 @@ Each day:
 - `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:

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('-'));

package/docs/MEDIA-GUIDE.md

@@ -0,0 +1,298 @@
+# TripKit Media Guide
+
+Turn the photos and videos from a finished trip into an interactive map where every
+stop shows what you actually captured there — and an optional, agent-assisted workflow
+for captioning and fixing matches.
+
+This guide covers:
+
+1. [What you get](#what-you-get)
+2. [Quick start](#quick-start)
+3. [How matching works](#how-matching-works)
+4. [The review file, field by field](#the-review-file-field-by-field)
+5. [Letting an AI agent do the review](#letting-an-ai-agent-do-the-review)
+6. [The `media` schema](#the-media-schema)
+7. [Using URLs instead of local files](#using-urls-instead-of-local-files)
+8. [Troubleshooting](#troubleshooting)
+9. [Command reference](#command-reference)
+
+---
+
+## What you get
+
+Once media is attached to a trip, the rendered HTML gains:
+
+- **Per-stop galleries** — a thumbnail strip and a `📷 N` count badge on each stop card and map popup.
+- **A marker cue** — stops with media show a `📷 N` badge on their map marker; click it to jump straight to the photos.
+- **A full-screen lightbox** — arrow keys / swipe / click to navigate, `Esc` to close, inline video playback, with each item's caption and capture time/GPS.
+- **A photo-pin layer** — a toggleable map layer (the **📷 Photos** button, top-right) that drops a pin at the exact GPS of every geotagged item, separate from the day-numbered stop markers.
+
+Stops without media render exactly as before — everything here is additive and optional.
+
+---
+
+## Quick start
+
+You need: a finished `trip.yaml` (the same file the renderer already uses) and a folder of
+photos/videos from the trip. Photos with EXIF GPS + timestamps match automatically; others
+can be placed by hand (or by an agent) in the review step.
+
+```bash
+# 1. Match your media folder to the trip's stops.
+#    Writes trip.media-review.yaml — nothing in trip.yaml changes yet.
+npx tripkit media ./my-photos trip.yaml
+
+# 2. Open trip.media-review.yaml. Add captions, fix any wrong matches,
+#    and place the items under "unmatched" that you want to keep.
+
+# 3. Merge the reviewed media into the trip.
+npx tripkit media apply trip.media-review.yaml trip.yaml
+
+# 4. Re-render. The map now shows your photos.
+npx tripkit trip.yaml trip.html
+open trip.html
+```
+
+> Running from a git clone instead of npx? Use `node convert.js …` in place of `npx tripkit …`.
+
+**Thumbnails (optional).** If [`sharp`](https://www.npmjs.com/package/sharp) is installed,
+step 1 also writes downscaled thumbnails to `my-photos/thumb/` and references them for fast
+map/gallery loading. If `sharp` isn't installed, the step still works — it just uses the
+full-resolution images directly. Install with `npm install sharp` to enable thumbnails.
+
+---
+
+## How matching works
+
+`tripkit media` reads each file's EXIF metadata and assigns it to a stop using two signals:
+
+1. **Timestamp → day.** The photo's `DateTimeOriginal` is matched to the day whose `date`
+   falls on the same calendar date. (The year comes from `trip.dates`.) This keeps a photo
+   taken on Day 3 from matching a closer-looking stop on Day 5.
+2. **GPS → nearest stop.** Within that day, the item is assigned to the geographically
+   nearest stop (great-circle distance). The result is tagged with a `confidence`:
+   - `high` — within ~3 miles of the stop.
+   - `medium` — within ~25 miles.
+   - Anything farther, or with **no GPS**, or whose date matches **no day**, goes to the
+     `unmatched` bucket for you to handle.
+
+Videos are routed to `unmatched` by default — most video formats don't expose GPS the way
+photos do, so they're left for you to place rather than guessed at.
+
+Nothing is destructive: matching only ever *proposes*. Your `trip.yaml` is untouched until
+you run `media apply`.
+
+---
+
+## The review file, field by field
+
+`tripkit media` writes `<trip>.media-review.yaml`. It's meant to be read and edited before
+applying. A trimmed example:
+
+```yaml
+trip_file: trip.yaml
+summary:
+  total: 6              # files scanned
+  with_gps: 5           # had EXIF GPS
+  with_timestamp: 5     # had an EXIF capture time
+  matched: 4            # confidently assigned to a stop
+  unmatched: 2          # need your attention
+  thumbnails: generated # or: "skipped (sharp not installed)"
+
+stops:
+  - day: 1              # ← which day (matches days[].number in trip.yaml)
+    stop_index: 0       # ← which stop within that day (0-based)
+    stop: Lower Yosemite Fall   # name, for your reference (not used on apply)
+    media:
+      - src: media/fall_01.jpg
+        type: photo
+        caption: ""               # ← WRITE THIS. Shown in the lightbox.
+        thumb: media/thumb/fall_01.jpg
+        lat: 37.7560              # original EXIF GPS (drives the photo-pin layer)
+        lng: -119.5965
+        taken_at: '2026-05-15T17:15:00Z'
+        confidence: high          # advisory only; removed on apply
+
+unmatched:
+  - src: media/random_sf.jpg
+    type: photo
+    caption: ""
+    lat: 37.7749
+    lng: -122.4194
+    taken_at: '2026-05-16T12:00:00Z'
+    reason: nearest stop "Glacier Point" is 156 mi away   # why it wasn't auto-matched
+    suggested_stop: Glacier Point
+  - src: media/no_gps.jpg
+    type: photo
+    caption: ""
+    reason: no GPS in EXIF
+```
+
+**What to edit:**
+
+| Goal | Do this |
+|------|---------|
+| Add a caption | Fill in `caption:` (this is the highest-value edit — it's what the lightbox shows). |
+| Move a photo to a different stop | Change its `day:` / `stop_index:` (under `stops:`), or move the item between entries. |
+| Keep an unmatched item | Give it a `day:` and `stop_index:` — then it's applied like any matched item. |
+| Drop an unmatched item | Leave it in `unmatched` without a `day`/`stop_index`. It's ignored on apply. |
+| Remove a wrong match | Delete the item from the file before applying. |
+
+**What's ignored on apply:** the `confidence`, `reason`, `suggested_stop`, and `stop` (name)
+fields are review aids — they're stripped when merging into `trip.yaml`. Only
+`src`, `type`, `thumb`, `caption`, `lat`, `lng`, and `taken_at` are written through.
+
+**`media apply` is idempotent.** Re-running it won't duplicate items already present (it
+matches on `src`), so it's safe to apply, render, tweak captions, and apply again.
+
+---
+
+## Letting an AI agent do the review
+
+The review step — captioning every photo and placing the unmatched ones — is exactly the
+kind of judgement work an AI agent is good at. The flow is designed so a human or an agent
+can do it; the agent never touches your originals, only the review YAML.
+
+A typical agent session:
+
+> **You:** "I ran `tripkit media ./trip-photos yosemite.yaml`. Here's the review file —
+> caption the photos and place the unmatched ones, then tell me the apply command."
+>
+> *(paste or share `yosemite.media-review.yaml`)*
+
+The agent should:
+
+1. **Caption each matched item** — concise, specific, grounded in what the photo shows and
+   the stop it's at. "Lower Yosemite Fall roaring with May snowmelt," not "Photo 1."
+   It can lean on `stop`, `taken_at`, and the trip's own descriptions for context.
+2. **Resolve `unmatched` items** — use `suggested_stop`, the `reason`, the filename, the
+   `taken_at` time, and the trip itinerary to decide a `day` + `stop_index`, or leave
+   genuinely unplaceable items unmatched. A `reason: no GPS` selfie taken at 8pm on Day 2
+   probably belongs at that day's dinner or lodging stop.
+3. **Flag the suspicious ones** — if `suggested_stop` is 150 miles away, that photo likely
+   isn't from a planned stop at all; better to leave it out than force a wrong pin.
+4. **Hand back the edited review file** and the exact `tripkit media apply …` command.
+
+If you use **Claude Code**, install the skill once and the agent already knows this flow
+(it's Phase 5 of the TripKit agent skill):
+
+```bash
+npx tripkit install-skill      # → ~/.claude/skills/tripkit/
+```
+
+Then: *"Use the tripkit skill to caption and place the media in this review file."*
+
+**Why review-in-the-middle?** The agent works on a separate YAML, not your photo files or
+your trip. You see every proposed caption and placement before anything is written, and the
+`media apply` step is a plain mechanical merge you run yourself. The intelligence is
+auditable, not a black box.
+
+After the agent returns the file, validate and render:
+
+```bash
+npx tripkit media apply yosemite.media-review.yaml yosemite.yaml
+npx tripkit validate yosemite.yaml     # surfaces e.g. media GPS far from its stop
+npx tripkit yosemite.yaml yosemite.html
+```
+
+---
+
+## The `media` schema
+
+Each stop (and, optionally, `lodging`) may carry a `media` array. It's purely additive to
+the [existing schema](../schema/tripkit.schema.yaml).
+
+```yaml
+stops:
+  - name: "Multnomah Falls"
+    lat: 45.576
+    lng: -122.116
+    image: "https://…"        # unchanged: the single hero/primary image
+    media:                    # the gallery
+      - src: "media/IMG_2401.jpg"   # relative path OR full URL (required)
+        type: photo                  # "photo" | "video"
+        thumb: "media/thumb/IMG_2401.jpg"  # optional; renderer falls back to src
+        caption: "620-ft waterfall from the lower viewpoint"  # optional
+        lat: 45.5762                 # optional EXIF GPS; powers the photo-pin layer
+        lng: -122.1158
+        taken_at: "2026-04-07T14:32:00"    # optional ISO 8601 capture time
+```
+
+- `image` (the original single-image field) is untouched and still used as the hero/primary.
+  `media` is the new gallery shown in cards, popups, the lightbox, and the marker badge.
+- Only `src` and a valid `type` are required per item; everything else is optional.
+- Items that include `lat`/`lng` also appear as individual pins on the **📷 Photos** map layer.
+
+`tripkit validate` checks every media item has a `src` and a valid `type`, and **warns**
+when an item's GPS is more than ~25 miles from its stop — a strong hint it was placed on the
+wrong stop.
+
+---
+
+## Using URLs instead of local files
+
+`src` (and `thumb`) accept either a **relative path** or a **full URL**.
+
+- **Relative paths** (the default from `tripkit media`) keep full-resolution media, but the
+  output is now an HTML file *plus* its media folder — ship them together.
+- **URLs** (e.g. photos you've uploaded to S3, Cloudinary, Google Photos, or anywhere with a
+  direct link) keep the output a **single, self-contained, shareable HTML file** with no
+  media folder to carry around.
+
+You can mix both in one trip. To use URLs, either point `src` at them when hand-editing the
+review file, or swap the relative paths for URLs in `trip.yaml` after applying.
+
+---
+
+## Troubleshooting
+
+**"Missing dependency exifr."** The ingest step needs it: `npm install exifr` (or just
+`npm install` in a clone — it's a normal dependency). Only the `media` command needs it; the
+renderer and `convert` don't.
+
+**Thumbnails were skipped.** That's the `sharp`-not-installed path; it's fine. Run
+`npm install sharp` to enable them. The review file's `summary.thumbnails` tells you which
+path ran.
+
+**Everything landed in `unmatched`.** Usually one of:
+- The photos have no GPS (phone privacy settings, screenshots, exported/edited copies that
+  stripped EXIF). Place them by hand using `day` + `stop_index`.
+- The photo dates don't line up with any day's `date`, so the day filter excludes every
+  stop. Check that `trip.dates` has the right year and each day's `date` is correct.
+
+**A photo matched the wrong stop.** Edit its `day`/`stop_index` in the review file before
+applying, or move it to the right `stops:` entry. If you already applied, fix it in
+`trip.yaml` (the `media` array under that stop) and re-render.
+
+**Videos didn't match.** Expected — they're routed to `unmatched` by default. Give them a
+`day` + `stop_index` to place them; they play inline in the lightbox.
+
+**The marker badge / photo-pin layer didn't appear.** The badge only shows on stops that
+have `media`; the **📷 Photos** toggle only appears when at least one media item has its own
+`lat`/`lng`. If your items lack GPS, the galleries and lightbox still work — just not the pins.
+
+---
+
+## Command reference
+
+```text
+tripkit media <folder> <trip.yaml>
+    Scan <folder> for photos/videos, read EXIF GPS + timestamps, auto-match each
+    to the nearest stop on the matching day, optionally generate thumbnails, and
+    write <trip>.media-review.yaml. Does not modify <trip.yaml>.
+
+tripkit media apply <review.yaml> <trip.yaml>
+    Merge the reviewed media into <trip.yaml>'s stops[].media[]. Idempotent.
+
+tripkit validate <trip.yaml>
+    Validate the trip, including media (src present, type valid, GPS sanity).
+
+tripkit <trip.yaml> [output.html]
+    Render to interactive HTML (auto-validates first).
+```
+
+Supported media extensions: photos — `.jpg .jpeg .png .heic .heif .webp .tif .tiff`;
+videos — `.mp4 .mov .m4v .avi .mkv .webm`.
+
+See also: the [README](../README.md) for the project overview and the
+[agent skill](../agent/SKILL.md) (Phase 5) for the agent-facing version of this flow.

package/docs/README.md

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

package/examples/oregon-spring-2026.yaml

@@ -307,6 +307,21 @@ days:
         duration: "2–3 hrs (loop)"
         reservation_required: false
         navigate_url: "https://www.google.com/maps/dir/?api=1&destination=Multnomah+Falls+Oregon"
+        # Post-trip media demo — `src` can be a relative path (from `tripkit media`) or a URL.
+        # These carry lat/lng, so they also appear in the toggleable photo-pin map layer.
+        media:
+          - src: "https://images.unsplash.com/photo-1546587348-d12660c30c50?w=1600"
+            type: photo
+            caption: "Multnomah Falls roaring with spring snowmelt — lower viewpoint"
+            lat: 45.5762
+            lng: -122.1158
+            taken_at: "2026-04-07T14:32:00"
+          - src: "https://images.unsplash.com/photo-1559521783-1d1599583485?w=1600"
+            type: photo
+            caption: "Benson Bridge between the upper and lower falls"
+            lat: 45.5765
+            lng: -122.1155
+            taken_at: "2026-04-07T14:40:00"
 
       - name: "Latourell Falls"
         lat: 45.537