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 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

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
• 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

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 across SE/DK/DE/AT/IT (db-rest HAFAS proxy). Covers SJ, Nightjet, ICE, Trenitalia. Italo not covered.