Tours as documents

The same grammar as scripts and skills. A tour's authoring document is a TourSpec: the tour's fields, its screens (read-only, for reference) and its steps, each keyed by a stable ref. Storage geometry never appears in it; the server expands what you write and keeps every field you did not touch, so a nudge someone made in the builder survives your typo fix.

GET  /v1/tours/{id}/spec       tours:read    the document and its version
POST /v1/tours/{id}/propose    tours:read    diff + lint, writes nothing
PUT  /v1/tours/{id}/spec       tours:write   apply against baseVersion
POST /v1/tours/{id}/publish    tours:write   freeze a revision for visitors

A step

{
  "ref": "approvals-second",
  "screen": "<screen id>",
  "at": 8.4,
  "anchor": { "region": [0.24, 0.26, 0.33, 0.21] },
  "title": "Approvals live here",
  "body": "Anything over $5k routes to a second approver automatically.",
  "advance": "auto",
  "advanceAfterSecs": 7.6,
  "narrate": true,
  "openWhen": ["how approvals work", "second approver"]
}

anchor is "center" for a lightbox, { "element": "button.submit" } for a selector, or { "region": [x, y, w, h] } in 0–1 fractions of the screen. advance is auto, click or ask; ask holds the frame for the agent and needs an agent-led tour. A step never moves between screens: remove it and add a new ref.

The loop

1. GET …/spec, keep version.
2. Edit the steps and POST …/propose with { "spec": { "steps": [...] } }. You get a diff by ref (added, removed, changed fields, reordered) and problems.
3. Fix errors, propose again. Warnings do not block.
4. PUT …/spec with { "spec", "baseVersion": version }. 409 stale means the tour changed under you: re-read and re-diff. 400 lint-failed carries the problems.
5. POST …/publish when a person has approved.

Lint rules: unknown screen, empty body, duplicate or missing ref, ask on a self-playing tour, auto without a duration, at past the screen's end, a moved step, vocabulary (the product is a tour; the older word is refused) as errors; two steps within half a second, a screen with no steps, and an unverified selector as warnings. Selectors are not checked against the screen yet; the element inventory is a later piece.

Narration audio is never regenerated by an apply: an unchanged body keeps its recording, and narration text follows the body unless a person wrote their own.