# What roamgap is — project specification

> The product brief in plain language. Source of truth: `specs/PROJECT.md`
> (served verbatim, with the full spec set, at https://roamgap.ike.work/llms-full.txt); this
> page paraphrases for public reading.

## In one line

roamgap is a **smart holiday optimizer**. Given a country and a PTO budget, it
returns the calendar trips that maximise continuous time off per PTO day spent.

## The core insight

A Tuesday public holiday plus the weekends around it can give a 5-day break for
just 2 days of PTO. The optimizer surfaces these opportunities automatically,
ranked by **efficiency** (total days off ÷ PTO days spent — see
https://roamgap.ike.work/about/algorithm).

## The tools

- **Annual planner** (https://roamgap.ike.work/year — primary, home-page) — enter your
  whole-year PTO budget and a max trip length; get five alternative year plans
  to pick from.
- **Plan a year for two** (https://roamgap.ike.work/overlap) — the same idea for two or more
  people across different countries: the breaks everyone can share, ranked by
  the least total leave and optimised against each country's public holidays.
- **Solo trips** (https://roamgap.ike.work/solo) — collect the breaks you like into an
  itinerary.
- **Group trips** (https://roamgap.ike.work/groups) — plan with a whole crew; everyone drops
  their own availability and the engine finds the shared window.

A reference **calendar** (https://roamgap.ike.work/calendar) shows any country's weekends and
public holidays for a year, with no optimization.

## What's free

The core optimizer is free and complete — the annual planner's five plans, both
budget modes, the full filters, the reference calendar, and **regional** (ISO
3166-2 state/province) accuracy wherever we have the data. We do not throttle
results or paywall basic correctness. A **free account** adds cross-device saved
searches, calendar export (.ics / Google), and email alerts. Free-tier searches
persist only in the browser session, and we say so plainly.

Paid tiers (later) add historical data, multi-country overlap, AI destination
recommendations, group/shared planning, and unlimited saved itineraries — never
baseline correctness or the free features above.

## Principles

- **Honest about limits** — session-only storage and historical-data
  uncertainty are surfaced in the UI, not hidden.
- **AI-discoverable** — every content page has a Markdown twin; the API
  publishes JSON Schema and OpenAPI so agents can call it directly.
- **Privacy-respecting** — analytics run only after consent
  (https://roamgap.ike.work/legal/privacy).
- **Spec-first, test-first** — no behaviour change ships without a spec change
  and a failing test first.

## Source

- This page: https://roamgap.ike.work/about/spec
- How trips are scored: https://roamgap.ike.work/about/algorithm
- Full normative spec (verbatim): https://roamgap.ike.work/llms-full.txt
- API entry points: https://roamgap.ike.work/api/openapi.yaml