Tutorial videos

What it is

• One list feeds everything. The onboarding inbox cards, the guide's Tutorial Videos page and the videos placed on feature pages all read the same video list. There is no second list to update.
• The Tutorial Videos page shows every video with its title, a one-line description and a player. Under a video that also lives on a feature page, Read the guide → jumps to that page.
• Videos on their pages. A guide page shows a video wherever it carries a marker naming that video. A marker for a video that is not in the list yet stays invisible, so a page can be prepared before its video is finished.
• New users only in the Inbox. The Inbox offers a new video card only during a user's first 30 days (counted from their first video card, which arrives the moment setup finishes). After that, new videos reach them through the Tutorial Videos page.

Where to find it

• In the app: open Help (Ctrl+Shift+/) and press ▶ Videos in its header. On a phone, the Help panel's Watch tutorial videos button opens the page in your browser.
• On the web: the help guide → Getting Started → Tutorial Videos (docs.omniscio.com/#tutorial-videos).
• Adding, removing or reordering videos is an owner-only task done from a session — see For agents below.

How it behaves

• Videos are Omniscio-owned. Every Shares delete, revoke, account removal and storage limit is tied to whoever owns a share. Each tutorial video is handed to Omniscio itself when it is added, so it leaves the publisher's Shares list and storage total, and nobody's cleanup can reach it. Playback is unaffected.
• The guide updates at each help-site publish. A newly added video reaches new users' Inboxes right away and the Tutorial Videos page at the next publish. A video whose link no longer works is left out, and the publish log names it; if the live list cannot be read, the guide publishes with the list built into the app and says so.
• Players load only on the page you open, so reading an unrelated part of the guide never starts a video.
• The one limit: an Inbox card a user already received keeps the link it was sent with. If a video is re-published, older cards keep the old link — the Tutorial Videos page always has the current one.

For agents

Add a tutorial video

One call re-encodes the file to the standard profile, publishes it, adds it to the list and hands it to Omniscio. Owner (install-wide) token only:

POST /onboarding-cadence/add-card with { "path": "C:/path/to/video.mp4", "id": "tutorial-snooze", "title": "Snooze", "blurb": "Hide a session until you need it." }

• Use the reserved id from the table below — it is what makes the video appear on its guide page. A new topic needs a new kebab-case id plus one marker line on its guide page in docs/help-site/public/index.html: <div class="tutorial-video" data-video-id="<id>" hidden></div>.
• Same id again = replace that video; its card keeps its place in the order.
• The reply carries "protected": true. If it says false with a warning, the video is live but still in the publisher's account — run POST /onboarding-cadence/protect-video with { "url": "<the card's video link>" }.

Reserved id	Shows on the guide page
welcome-tour	Welcome (live)
tutorial-hubs	Hubs
tutorial-session-lifecycle	Sessions
tutorial-catch-up	Inbox
tutorial-snooze	Inbox → Snoozing Inbox Items
tutorial-zap	Chat Interface → Zap
tutorial-quick-replies	Quick Replies
tutorial-search	Search
tutorial-plain-speak	Plain Speak
tutorial-hotkeys	Keyboard Shortcuts
tutorial-just-ask	CLI Control API

Manage the list

All owner-token routes; each change reaches the app at once and the guide at the next publish.

• GET /onboarding-cadence/cards — the live list, in order.
• POST /onboarding-cadence/remove-card { "id": "…" } — takes a video off the list; the video stays hosted so Inbox cards already sent keep playing.
• POST /onboarding-cadence/reorder { "ids": [ … ] } — must name every current id exactly once; a list built before someone else's change is refused rather than losing a video.
• POST /onboarding-cadence/protect-video { "url": "…" } — hand an already-published video to Omniscio (admin-only cloud action tutorialVideo.protect, reserved owner omniscio-system).

How the guide list is built

npm run docs:sync-videos (a help-site publish-lane step, scripts/rebuild-tutorial-videos.ts) reads the live list through the onboarding-cadence relay, falls back to the built-in list with a named warning, keeps only links to a minted Omniscio /embed player, drops a video whose link answers 404/410 by name, keeps one it could not check, and names any guide marker that matches no video. Its output docs/help-site/public/tutorial-videos.json is generated and never committed. The contract is tutorial-videos-library-contract.md.

Related

The Help panel page (help-and-docs-panel) explains the in-app help browser the Videos button lives in. First-time setup (first-time-setup) explains where a new user's first, welcome video card comes from.