# Versioned trip planning for agents

Unsold Adventures stores one canonical plan.json in a Git repository for each saved plan. The site, JSON, Markdown and agent tools read accepted revisions of that document.

## Connect

1. The traveler signs in with verified email at /plans/, then opens /for-agents/.
2. The traveler grants authoring access and supplies the credential through the agent client's secure authorization settings.
3. Connect the client's Streamable HTTP MCP transport to the endpoint displayed on that page. Send Authorization: Bearer followed by the credential in the transport header. Keep it out of prompts, plan documents, Git remotes and shared URLs.
4. Read-only public plan discovery needs no credential. Grants expire after one day and can be revoked on /for-agents/.

## Shared library

GET /api/v1/itinerary-library discovers editorial, creator and explicitly published traveler itineraries. Private drafts are excluded. GET /api/v1/itinerary-library/{kind}/{id}?revision={revision} reads a pinned editorial or creator starting point. Published traveler plans use get_artifact_plan. Humans start at /itineraries/ and choose Make my version; the saved derivative preserves authoritative credit and pinned ancestry.

## Plan through tools

- list_artifact_plans discovers published starting points.
- get_artifact_plan reads the accepted plan and its revision.
- create_artifact_plan creates a private scratchpad from destination, goals, days, pace, travelers and constraints.
- update_artifact_plan saves a complete plan against the expected revision. A conflict requires reading the current version before retrying.
- fork_artifact_plan pins one source revision. compose_artifact_plan selects stops from multiple sources; preserve every source's credit and ancestry.
- match_artifact_plan_tours reads current published inventory. Confirm dates, availability, transfers and unsupported personal requirements before booking. Use get_booking_link for the booking URL.
- list_artifact_plan_revisions reads the owner's accepted history.

## Named alternatives

- list_itinerary_alternatives and get_itinerary_alternative read owner-authorized routes.
- create_itinerary_alternative snapshots the current route; update_itinerary_alternative edits an inactive route.
- select_itinerary_alternative chooses a complete route using the current main revision, target alternativeRevision and selectionVersion. The outgoing route remains available. Selection does not publish.
- sync_itinerary_alternative_git validates a pushed inactive alternatives/{id} branch against its accepted revision.

Each alternative begins with an independent snapshot root and then has linear Git history. Credit and document ancestry connect remixes; an independent remix repository does not inherit the source Git commit graph. Whole-route selection is supported; selective Git merging is not.

## Edit through Git

1. Call get_artifact_git_credentials for short-lived owner-authorized read or write access.
2. Clone the returned clean HTTPS remote using a secure Git credential helper. Never store credentials in plan.json or the remote URL.
3. Edit plan.json, commit and push to main. Preserve plan identity, sources, ancestry, contributors and substitution history.
4. Call sync_artifact_plan_git with the last accepted revision. A raw push does not become accepted or public until validation succeeds.
5. Revoke temporary credentials through DELETE /api/v1/artifact-plans/{id}/credentials, sending the token in a private JSON body. Authoring grants can also be revoked on /for-agents/.

## Privacy and publication

Plans start private. Only the verified owner's browser session can publish. Agent authoring credentials cannot publish or grant more access. The published branch contains validated snapshots; newer private drafts are never included in public reading surfaces. Publishing permits attributed derivatives by other owners. Private source material must be published before a derivative can be published.

## Upstream changes

Only trusted editors submit verified closure facts. The server applies eligible replacements to dependent plans, preserving schedule, stable stop identities, credit and history. Unknown personal constraints or missing verified replacements require review. Viewers can dismiss the displayed update notice; that does not erase the event from the plan's Git history or JSON.