Content freshness

Video ages faster than docs. Content freshness closes the gap two ways, neither of which gates publishing. Learners can report a problem on any lesson. And three steps check your videos against your docs: 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. 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 a finding 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.

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.

Reviews check what learners see, so a video's claims only join a review once the lesson is published with that video in it. Until then the claims block says so — "Not in reviews yet" and why (the lesson isn't published, or the published version doesn't include this video). Claims in template and library lessons are never reviewed; their copies in courses are.

From a new video to its first review

1. Put the video's link on its own line in a lesson. The Transcripts & claims drawer appears under the editor with "1 without transcript".
2. Bring in the transcript: Fetch transcript for Mux, HLS streams with subtitles, and direct video files, or paste it for YouTube, Loom, Vimeo, and Wistia. This is the one step you do yourself.
3. The claims appear under the video on their own, within seconds. While the lesson is a draft they read "Not in reviews yet".
4. Publish the lesson. Its claims join the count on Admin → Freshness.
5. The next review — Run now or your schedule — checks them against your docs.

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.

Connecting your docs

Point Mastria at your docs first, in Admin → 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.

Saving checks the connection the way a review reads it — "Saved and connected: acme/docs@main at 3f9c2a1 — 212 files match your globs" — so a wrong repo name, branch, or token shows up right there, in plain words, instead of as a failed review later. The card also shows what the newest review last read (commit, files, passages).

Running a review

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; the card shows when the next one is planned. 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.

The page's What the next review checks card says exactly what that is — "24 claims from 3 videos in 2 published lessons" — and lists the lessons behind every skipped group (the first five per reason) and why: the video or the lesson isn't published yet, the claims are out of date since the transcript changed, or it's a template or library lesson. It also names published videos that have no transcript yet, since nothing they say can be checked, and how many muted claims are skipped on purpose.

Reading the report

• Anything that contradicts the docs is listed at the top — each lesson with open changed findings, linked to its rows — and courses and lessons with findings come first below. Show tabs narrow the rows to Changed, Unclear, Holds, or Muted.
• Every row shows both sides: the claim with its verbatim transcript quote and timecode, and the docs passage the verdict is based on, quoted with its file path. The timecode opens the video at that second — YouTube, Vimeo, Loom, Wistia, Mux (in Mux's hosted player), and direct video files.
• A lesson with several unclear claims shows them folded into one line on the All tab — usually topics your docs don't cover — so a real finding never drowns in them. Open it, or use the Unclear tab, to read what each check looked for.
• The counts (on the report and on each run in the list) are live: a finding you mute stops counting as changed and shows as muted instead.
• A review that couldn't read your docs (wrong repository, branch, or token) says so in plain words, with a link to the docs source settings and a Try again button for after the fix.
• 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 in the workspace

Findings follow you into the editor: a lesson with a claim whose most recent verdict is changed wears a clock in the course outline, and its editor shows a "Freshness: N claims changed in the … review" line linking straight to that lesson's findings in the report. In the Transcripts & claims drawer, every claim that has been checked shows its latest result — Changed, Unclear, or Holds — linked to the review that decided it. The admin Dashboard carries a Content freshness card too: how many claims currently contradict the docs, the last review, and the next planned one. A review in progress never blanks earlier warnings — each claim keeps its last verdict until it is checked again.

Learner reports

Every lesson's footer carries Report a problem with this lesson for signed-in learners. They pick what's wrong — It's out of date, Something doesn't work, It's hard to follow, A typo or mistake — and can add a note. Only your team sees reports; the form tells the learner so, and that it comes with their name and email. Reporting never holds anything back: no lesson, completion or certificate waits on it.

Reports land in Learner reports at the top of Admin → Content freshness — no docs source needed. One row per lesson: how many open reports and why, the newest notes with who sent them and when, Open lesson to fix it, and Mark as reviewed.

A report is open while the version of the lesson it was made on is still live and nobody has marked it reviewed. Publishing the lesson again clears its reports.

So the usual path is: read the notes, fix the lesson, publish — its reports close on their own. Mark as reviewed is for a report that needed no edit (it was a misunderstanding, or the problem was outside the lesson). A learner has at most one open report per lesson version: sending again changes it, and after a publish they can report the new version. If you publish while someone is reading, their report asks them to reload first, so a complaint about the old version never lands on the one that fixed it.

Your team's reports aren't listed, like everywhere learners are counted. The lesson editor shows a line when the lesson has open reports, linking here, and the dashboard's Content freshness card counts them. Every report — open, reviewed, or cleared by a publish — exports as lesson-reports.csv, and the lesson.reported webhook sends each one as it's made.