# Guided tours

Curated walkthroughs of selected paintings. Visitors open **Tours** on the timeline, pick a published tour, and walk a 3D hall (`VirtualGallery` mode `tour`). Opening a frame shows stop notes on painting detail; prev/next follow tour order.

## Status

| Status | Who sees it |
|--------|-------------|
| `draft` | Curators only (Tour editor + `GET /api/tours/:id` when signed in) |
| `published` | Everyone via Tours popup + public API |

Tour stop **body** text is English-only in v1 (stored on `tour_stops.body`). UI chrome is EN/RU via i18n.

## Data model

Migration: `db/migrate-tours.sql` (applied by `npm run dev:migrate`).

| Table | Role |
|-------|------|
| `tours` | Title, description, `status`, optional `cover_painting_id` |
| `tour_stops` | Ordered stops: `tour_id`, `painting_id`, `sort_order`, `body` (unique per tour+painting) |

Included in `scripts/harmonize-db.js` catalog sync.

## Curator editor

Home header → **Tour editor** (curators). Create tours, set draft/published, search-add paintings, reorder, edit stop text, save.

## Visitor flow

1. Timeline → **Tours** → modal of published tours  
2. Select tour → `GET /api/tours/:id` → winged 3D hall (left wall first → right wall last, stop order preserved)  
3. Click frame → painting detail with tour notes + stop-ordered navigation  
4. Back / hall exit → timeline  

Hall hang rules match artist and movement galleries — see [basics.md — Virtual gallery](basics.md#virtual-gallery-3d-halls).

## API

See [API.md](API.md#tours). Audit actions: `tour.create`, `tour.update`, `tour.delete`, `tour.stops`.

## Out of scope (v1)

- Russian tour body translations  
- Auto-generated / AI tours  
- Audio or timed slideshow  
- Editing tours from painting detail