Content freshness | Mastria Docs

Video ages faster than docs. Content freshness closes the gap in three steps, none of which gate publishing: every embedded video can carry a transcript, the platform extracts the checkable claims the video makes about your product, and a docs review — on your cadence or your click — checks each claim against your current documentation and points at the exact second that no longer matches.

Video transcripts & claims

Every video a lesson embeds can carry a transcript — the raw material for the freshness checks that compare what your videos say against your current docs (and, later, for search). Transcripts are authoring-side only: learners never see them, and they're never a publish requirement.

When a lesson embeds videos, a Transcripts & claims drawer appears under the editor, one row per video, with a "N without transcript" count. How a transcript gets in depends on where the video lives:

Mux (player.mux.com or stream.mux.com links) — one click. Enable auto-generated captions on the asset in your Mux dashboard, press Fetch transcript, and the caption track lands as the transcript. Any other HLS stream whose manifest carries a subtitle track works the same way.
Direct video files (.mp4/.webm on your own CDN) — Fetch transcript sends the URL to a speech-to-text service; the row shows "Transcribing…" and fills itself in a minute or two.
YouTube, Loom, Wistia, Vimeo — paste. YouTube shows the full transcript under every video ("Show transcript" — copy, paste, done); Loom and the others export from their own apps. Thirty seconds per video, once — transcripts are kept until you replace or remove them.

Timestamps in fetched transcripts are kept ([1:05] … line prefixes), so later tooling can point at the exact moment in the video. Pasted text is stored exactly as pasted — timestamps welcome but optional.

Claims

The moment a transcript lands, the platform reads it and extracts its claims: the checkable statements the video makes about your product — commands, flags, API names, UI paths, defaults, version requirements, behavior. Each claim appears under its video with the timecode, a kind chip, and the verbatim transcript quote it came from (a claim without a real quote is dropped, never guessed at). These are what a docs review judges against your documentation — so a finding points at the exact second of the exact video that no longer matches (see "Docs reviews" below).

You don't manage claims; you only correct them. If a claim is true on purpose — "this course teaches the 2.x LTS deliberately" — press Mute and say why (the reason is required). Muted claims are skipped by future checks, and the mute survives re-extraction as long as the claim text stays the same. Replacing a transcript re-extracts automatically; Extract again is there for retries and refreshes.

Docs reviews

The payoff of transcripts and claims: press one button and every claim your published lessons make gets checked against your current documentation — and each finding points at the exact second of the exact video that no longer matches. Nobody re-watches anything.

Point Mastria at your docs first, in Settings → Docs & freshness: a GitHub repo (owner/name), a branch, and path globs — the default **/*.{md,mdx} covers Mintlify, Docusaurus, and MkDocs sites as they are (add openapi.json or similar to index a spec file too). Public repos need no token; private ones take one, and the content-sync token works as a fallback.

Reviews run from Admin → Freshness. Press Run now — after a release is the natural moment — or set Scheduled reviews (monthly or quarterly, right on that page) and a review runs by itself; Run now keeps working either way, and a manual run resets the schedule. Only one review runs at a time — a second Run now joins the one in progress. A run indexes your docs at their current commit, checks every unmuted claim of every published lesson whose video is in the published lesson body (claims from a transcript you've since replaced wait for their re-extraction), and files a report:

Findings are grouped course → lesson, with changed first. Every row shows both sides: the claim with its verbatim transcript quote and timecode (linked into the video where the provider supports it), and the docs passage the verdict is based on, quoted with its file path. No quote, no alert — a verdict that can't cite the docs is reported as unclear, never as a finding.
Verdicts are changed / holds / unclear — three honest states, never a forced binary. "Checked, all clear" is recorded too, so fine and never looked can't be confused — and it only appears when every claim was verified to hold; a run whose claims came back unclear says so instead.
Each run is a record: it pins the docs commit it read, so a report stays meaningful after the docs move on.
Mute works right from the report (reason required), and muted claims are skipped by future runs.
Rows marked carried were not re-judged: nothing the check would read — neither the claim nor the docs passages retrieved for it — moved since the previous review, so the previous verdict carries forward. Retrieval itself still runs fresh every time, which is why a docs change always surfaces; carry-forward is what keeps a steady-month scheduled review nearly free.

Findings follow you into the workspace: a lesson with a claim whose most recent verdict is changed wears a dot in the course outline rail, and its editor shows a "Freshness: N claims changed in the … review →" line linking straight to the report. A review in progress never blanks earlier warnings — each claim keeps its last verdict until it is checked again. Warnings only — publishing never gates on freshness.

Reviews never gate publishing, never edit content, and never run on docs merges — a review runs on your cadence or your click, nothing else. Hidden and restricted courses are checked like any other: freshness is about content truth, not learner reach.