Roadtrippers

Build me a personal road-trip itinerary planner for trips I enter, as a narrow substitute for Roadtrippers. Requirements:

- Use Next.js, TypeScript, SQLite, and MapLibre GL. Keep trips, ordered stops, dates, notes, manually entered reservations, and source timestamps in a local database.
- Let me add stops by address or map click. Geocode only user-entered places through a configured map provider; keep manual coordinates editable when the provider is unavailable.
- Show trip days, stop order, driving legs, local timezones, reservation notes, and a conflict warning when dated entries overlap. Route estimates carry provider and fetch time.
- Save a trip bundle as JSON and printable Markdown or PDF. Keep the saved itinerary readable without a network connection; do not imply global offline maps.
- A route or geocoding error must preserve stops and reservations and display the unverified leg. Never turn a provider estimate into a booking or live availability claim.
- Acceptance: add three stops across two local dates, reorder one, attach a manual reservation, simulate a route API failure, and verify JSON export/import preserves stop IDs, order, dates, and notes.
- Put an optional map key in .env. No accounts, telemetry, booking engine, live inventory, or turn-by-turn navigation. README covers map licensing/cache limits and backup.

# AGENTS.md — Build guide for Roadtrippers

## Project scope
Map a user-planned road trip with manually entered stops, notes, and reservations, and keep an offline itinerary without claiming live proprietary availability.

Catalogue verdict: no. A consolation build is possible, but the paid product's decisive value sits outside a solo rebuild. For Roadtrippers, map a user-planned road trip with manually entered stops and notes. The hard boundary is proprietary place database, route intelligence, rv data, maps, and mobile navigation, plus proprietary live data and network coverage.
Use the implementation prompt below to define the deliverable. Complete each phase's acceptance checks before extending the scope.

## Working agreement
- Inspect the repository and its existing instructions before choosing paths, dependencies or commands. Keep one coherent stack and explain changes to the proposed architecture.
- Plan a vertical slice that accepts a real input and produces the useful output described below. Persist only the state the prompt calls for; respect memory-only and upstream-managed workflows. Use fixtures only when they are clearly labelled.
- After scaffolding, document the actual install, development, check and build commands in README and keep them synchronized with the package or project manifest. Do not report commands as successful unless they ran.
- Work in small steps. At handoff, list implemented flows, checks actually performed, remaining blockers, and any credentials or provider setup the owner must supply.
- Do not publish, spend money, contact customers, delete source data or run irreversible migrations without the project owner's authorization.

## Prerequisites
- modern browser
- MapTiler or compatible map key
- user-entered reservations
- optional public transit or weather API

## Stack and architecture
- Next.js and TypeScript for itinerary editing, MapLibre GL for the trip map, SQLite for local trip records
- Trip, dated stop, route leg, manual reservation, note, and exported bundle schemas with stable IDs

## Security and data integrity
- Accept only user-entered places and keep optional map credentials in .env
- Label external route data with provider and age; retain manual stops if the provider fails
- Keep reservation notes local and exclude live-booking claims

## Agent implementation rules
- Preserve stop IDs when the user reorders a trip
- Represent missing route estimates as unknown legs, never zero-distance legs
- Round-trip a three-stop itinerary through JSON export and import

## Optional agent skills and references
No installable skill is listed for this guide; use the project rules and the stack documentation.

Read the linked SKILL.md and its dependencies before adding a skill. Select only the skills matching this project's runtime and task; their documentation does not supply API access, credentials or approval to perform external actions. Pin the reviewed revision where the tool supports it. Follow the chosen agent's documented project-level installation mechanism.

## Distribution ideas
These are optional planning notes. Obtain the owner's approval before publishing or contacting anyone.
- Demonstrate a two-day user-planned route and an offline printable itinerary
- Explain that booking availability, global offline maps, and turn-by-turn navigation are outside the build

## Engineering roadmap
1. Phase 1: Model trips, stops, legs, reservations, and notes with stable IDs and local dates. Seed a three-stop, two-day example.
2. Phase 2: Build stop editing and MapLibre display; geocode only submitted places and store coordinates plus provider timestamp.
3. Phase 3: Show day timelines, route estimates, and overlap warnings. Preserve manual edits when routing fails.
4. Phase 4: Export JSON and printable itinerary; import the JSON into a fresh database without changing stop order or IDs.
5. Phase 5: Simulate geocode and route failures, inspect unverified labels, and document map key, licensing, and offline limits.

## Paid-product capabilities outside this build
- proprietary place database, route intelligence, RV data, maps, and mobile navigation
- live fare and inventory data
- global routing dataset
- crowdsourced trail intelligence
- booking, disruption support, and offline map fleet

## Implementation prompt
Build me a personal road-trip itinerary planner for trips I enter, as a narrow substitute for Roadtrippers. Requirements:

- Use Next.js, TypeScript, SQLite, and MapLibre GL. Keep trips, ordered stops, dates, notes, manually entered reservations, and source timestamps in a local database.
- Let me add stops by address or map click. Geocode only user-entered places through a configured map provider; keep manual coordinates editable when the provider is unavailable.
- Show trip days, stop order, driving legs, local timezones, reservation notes, and a conflict warning when dated entries overlap. Route estimates carry provider and fetch time.
- Save a trip bundle as JSON and printable Markdown or PDF. Keep the saved itinerary readable without a network connection; do not imply global offline maps.
- A route or geocoding error must preserve stops and reservations and display the unverified leg. Never turn a provider estimate into a booking or live availability claim.
- Acceptance: add three stops across two local dates, reorder one, attach a manual reservation, simulate a route API failure, and verify JSON export/import preserves stop IDs, order, dates, and notes.
- Put an optional map key in .env. No accounts, telemetry, booking engine, live inventory, or turn-by-turn navigation. README covers map licensing/cache limits and backup.

## Completion evidence
Demonstrate the prompt's acceptance scenarios against the scoped workflow. Include setup from a clean checkout and failure recovery. Check persistence across restart and export/restore only for the state the prompt says to store; for memory-only tools, confirm that temporary content is discarded as specified. Record actual results and remaining limitations. A detailed plan alone does not establish a working replacement.