AGENTS.md - AI Assistant Context

This file contains preferences and requirements for AI assistants helping with travel planning for the Summer 2026 trip.

Preferences

The trip starts on June 11 and ends at July 4. We are mainly traveling with train (Interail). We are travelling to Italy and stopping along they way. Start and endpoint is Stockholm, Sweden. One traveller can only walk about 500 m (but short distance mobility is good steep stairs etc) so local travel need to include taxi, e-scooters, public transport, car rental etc.

Transport

• Night trains with couchette/sleeper beds preferred
• Arrive morning, depart afternoon/evening (or next day)
• Minimum 6 hours at each stop
• Can rent car for local exploration

Destinations

• Picturesque towns with moderate to no tourists
• Genuine local culture
• Excluded (visited before): Orta San Giulio, Berlin, Hamburg, Copenhagen, Prague, Belgrade, Venice, Cinque Terre, Genoa

Interests

• Culinary experiences, food markets
• Beaches (require reliable 20-25°C) — lake beaches are fine too
• Scenic views

Accommodation

• No pretentious "boutique hotels", no bland chains
• Prefer local family-run hotels catering to independent or in-country travellers

Research

• Regions.md — Italian regions shortlist with ratings
• Train-Routes.md — Stockholm to Italy rail corridors, night trains, gateway cities
• Interrail-Passes.md — Interrail pass options

Region Deep Dives

• Emilia-Romagna.md
• Friuli-Venezia-Giulia.md
• Marche.md
• Umbria.md
• Abruzzo.md
• Puglia.md
• Calabria.md

Saved Articles

• Southern Italy Itinerary: 2 Days in Matera
• Ostuni - Den idylliska vita staden på höjden
• Torre Guaceto: Nature, Sea & Silence in Puglia

Budget

• Budget is not a priority but neither is luxury.
• Prioritize comfort and experience over cost savings

Authoring rules for research documents

• Location-specific info stays with the location. Beaches, markets, hotel suggestions, food specialties, and anything else tied to a single town belong inside that town's section — not in a cross-cutting "Beaches" or "Markets" section.
• Cross-cutting sections only for genuinely regional content. Use them for region-wide overviews (e.g. coastline character, regional cuisine traditions, rail network summary, water temperature), not as a dumping ground for per-town items.
• One source of truth per fact. If a market belongs to Pesaro, don't list it under both "Pesaro" and a regional "Markets" section. Pick one — the town section.

Walkability framing

• Distance is the only walkability metric. Do NOT use terrain adjectives (flat, level, slope, gradient, steep, hilly, cobbled, stepped, stairs) when describing whether a place works for the 500 m walker. They are irrelevant — only continuous walking distance is.
• Walking info lives inside each town entry, as a single **Walking:** line giving concrete distances + any bridge-transit (taxi, e-bike, funicular, escalator, shuttle boat). No consolidated walking-distance table at the regional level.
• No prose about whether a place is "easy" or "hard" — let the distances speak.

Shared micromobility availability

• italian-micromobility.md is the source of truth for shared e-scooter and e-bike coverage by town, scoped to the index regions only (Emilia-Romagna, Friuli-Venezia Giulia, Marche, Umbria, Abruzzo, Puglia, Calabria). Consult it before suggesting a scooter/e-bike as a 500 m bridge option for a specific town. Note the 2026 Codice della Strada: scooters now need a helmet (which operators don't supply), so prefer e-bikes (helmet-exempt) or taxi as the bridge. When you confirm or discover new operator data (launches, exits, regulation changes), update the file in the same edit.

Tooling for agents

Source of truth

calendar/itinerary.py is the single source of truth for the day-by-day plan. The build pipeline derives two outputs from it:

1. calendar/italy-2026.ics — subscribed in Apple Calendar via a secret gist
2. Itinerary.md — auto-generated human-readable page on the website

Do NOT hand-edit Itinerary.md — it is overwritten on every build. Edit calendar/itinerary.py instead.

Website (Cloudflare Pages)

• Hosted at: https://italy-2026-e0r.pages.dev (production)
• Source: every .md at the repo root + calendar/README.md → pandoc → Web/*.html
• Index page: index.md (linked from /)
• Build config: Rakefile + Gemfile
• Templates: tools/template.html, tools/style.css, tools/rewrite-links.lua (.md → .html link rewriter)
• Build: bin/rake build — incremental, only rebuilds changed files. Includes regenerating Itinerary.md from calendar/itinerary.py.
• Publish: bin/rake publish — npx wrangler pages deploy Web --project-name italy-2026. Skips if nothing changed since .last_published.
• Force redeploy: bin/rake force_publish
• Lint: bin/rake lint — html-proofer link checks
• Setup if missing: bundle install (uses Gemfile)

Calendar (Apple Calendar subscription)

• Generator: calendar/make-ics.py → calendar/italy-2026.ics
• Sync script: calendar/sync.sh — rebuilds .ics if itinerary.py/make-ics.py/Train-Routes.md changed; pushes to gist only if content sha (excluding DTSTAMP) differs. Tracks last-pushed sha in calendar/.last-pushed-sha.
• Gist ID: b9921ca8dc846a76ca131507cd88e922 (jacobwallstrom, secret). See calendar/README.md for subscribe URLs.

Stop hook

.claude/settings.json wires a Stop hook that runs .claude/hooks/site-sync.sh after every assistant turn. The script:

1. Runs calendar/sync.sh → updates Apple Calendar gist if itinerary changed
2. Runs bin/rake build publish → regenerates Itinerary.md, rebuilds HTML, deploys to Cloudflare Pages if changed

Idempotent and silent on no-op (exit 0). On failure: exits 2 with a structured recovery guide written to stderr, which Claude Code injects back into the conversation for the next agent.

Timetable lookups

Use the eu-rail-timetable project skill to query live 2026 train timetables for DE/AT/IT via the bahn.de web API driven through a real browser (puppeteer MCP). Covers ICE, Nightjet, Trenitalia (FR/IC/ICN/R) incl. sleeper/couchette flags. The old db-rest HAFAS proxy is dead (2026 DB API migration retired noncd.db.de). Scandinavian legs (SJ/Snälltåget Hamburg/Berlin→Stockholm) are NOT returned by this engine — use sj.se / snalltaget.se. Italo not covered.

Google Maps reviews

Use the google-maps-reviews project skill to scrape header info + individual reviews for any Google Maps place. Requires the Launch Chrome CDP.app launcher running with the user signed into Google. Output is JSON ready for sentiment comparison across beaches, restaurants, hotels, etc.