Building an interactive site
A site at https://{prefix}.interactive.vidmoat.com is a home for the person's own interactive videos with nothing of ours around them. The videos are the point; the site is the frame. Every page should get a visitor to a player within one screen.
The tools: get_interactive_site, edit_interactive_site, publish_interactive_site (MCP and the API). In the app the same calls go through agentWorkspace with action: "interactive_site" and site: {tool, ...arguments}.
Workflow
- Read first.
get_interactive_sitewithvideos: true. It says whether a site exists (canCreate), its pages and everysectionId, itsproblemsand itsrev. Change only what was asked, bysectionId, and sendrevback. - Only published, shared videos. A site shows the account's own interactive videos whose choices are published and shared;
videos: truelists exactly those, with ids. A video the person names that is not on the list is published first (publish_interactivewithshare: true, when they agree), never guessed or swapped for another. - Name it once. Check a name with
get_interactive_siteandprefix: "name"(limited: one or two tries, not a loop over ideas), thenedit_interactive_sitewithcreate: {prefix, title}. Use the person's own name or brand; one site per account. - One theme.
setTheme:tone(dark,light),palette(warm,neutral,cool,forest,plum),fontandheadingFont(system,serif,mono,rounded),corners(soft,round,square),density(comfortable,compact,airy),width(normal,narrow,wide),playerAccent(videokeeps each video's own look,siteuses the site's),accent#RRGGBB. Match the films: dark for cinematic or night footage, light for tutorials and courses. Leave a token out to keep its default. - Home page in this order: a
hero(heading, a line, the strongest video asvideo, a button), then agridof the rest, then whatever explains (storyfor a branching film,text,about), then actaorlinkslast. One featured video, not three. - Few pages. Home alone is often enough. Add
filmsoraboutpages only when there is more than one screen of it.setNavlists them;setHeadergives the title, a tagline and a logo fromimages: true. - Batch the edit. One
edit_interactive_sitecall with all theops(applied all or none), then read the reply'sproblems. - Show, then publish. Give the person
previewUrl(their draft at its real address, for an hour). Publish withpublish_interactive_siteonly when they ask: it is a public page.publish: falsetakes it down at once.
Examples
{"create": {"prefix": "river-films", "title": "River Films"}}
{"rev": 3, "ops": [
{"op": "setTheme", "tone": "dark", "palette": "cool", "headingFont": "serif", "accent": "#4CC9F0"},
{"op": "setHeader", "title": "River Films", "tagline": "Short films you play"},
{"op": "addPage", "slug": "films", "title": "Films"},
{"op": "setNav", "links": [{"label": "Home", "page": ""}, {"label": "Films", "page": "films"}]},
{"op": "addSection", "page": "", "section": {"kind": "hero", "heading": "Films where you choose what happens next", "body": "Pick a path, then go back and take the other one.", "video": "<id from videos:true>", "cta": {"label": "See every film", "page": "films"}}},
{"op": "addSection", "page": "", "section": {"kind": "grid", "heading": "Play them all", "videos": ["<id>", "<id>"], "columns": 3}},
{"op": "addSection", "page": "", "section": {"kind": "story", "video": "<id>", "heading": "How it branches"}}
]}
{"rev": 4, "ops": [{"op": "updateSection", "sectionId": "<from the digest>", "set": {"heading": "New films every month", "body": null}}]}
Gotchas
- No custom code. No HTML, CSS, scripts, embeds or "custom styling" anywhere; never offer them. A refused value comes back with the allowed list: pick from it.
- Page
""is home. Other pages are slugs (films,about); a renamed slug carries its links with it. - Buttons (
cta) are{label, page}or{label, href}with anhttpsaddress.linksare https only. textis restricted Markdown:##and###, lists, bold, italic, https links. No HTML, no images.abouttakes a picture id fromimages: true, never a URL.- An accent can be refused when words on it, or it on the page, would be hard to read. Try a lighter accent on dark, a deeper one on light.
- Limits are refused, never cut: 6 pages, 12 sections a page, 12 videos a grid, 6 nav links, 10 links; a heading 90 characters, body text 600. Shorten the words yourself.
nullremoves an optional field inupdateSection; leaving it out keeps it.- Search engines can find a published site (a sitemap and video data come with it). Write each page's
titleanddescriptionfor a stranger searching;setSettingsindexing: falsekeeps a site out when the person wants it private. - A story map spoils games. By default it shows only the opening and its answers, with the scenes and endings counted. Use
reveal: "full"only for a lesson or a guide, never for a game or mystery, and never next to copy that promises a secret. - Posters matter. Players and grid cards show the video's poster until played; pick videos whose poster is a real title card, not a black first frame.
- Renaming the address (
edit_interactive_sitewithprefix) holds the old name and forwards it for a while; do not rename casually. - Hobby accounts are refused with the reason; say it plainly, do not work around it.