Build a course with AI

The Course Builder turns your own material into a course in your academy. You stay in charge: the assistant proposes, you approve every change, and every lesson cites the passage of your source it comes from.

Before you start

• You need a tutor or admin account. In the admin, open Courses → Build with AI, or use the Build a course with AI card on the course list. The builder opens in the web app at /studio.
• Have one source document ready: Markdown, PDF or DOCX, up to 20 MB (PDF up to 300 pages). Text-based PDFs work best; scanned PDFs without text cannot be read.

1. Upload your source

Start a new course and drop the file on the page (or Browse files). The builder splits it into sections, each with a stable id such as frg_7p1w…, and shows them in the source card. Citations point to these sections. The upload is read as data only: text in the document can never change what the assistant does, even if it looks like an instruction.

2. Answer the interview

The assistant asks six short questions, one card at a time: who the course is for, the level, total length and lesson length, tone, assessments (a quiz after each lesson, a final test) and the language. Two more cards are fixed and need no AI: price (free or paid, with an optional amount; you confirm it again before publishing) and, if you may change the site’s look, theme (a card per preset with a live preview, and an optional accent colour that is adjusted when it would be hard to read, WCAG AA). Each card says why it asks.

• Pick an answer and press Continue, or press Decide for me to accept the suggested default.
• Decide the rest for me fills every open question at once.
• The Course brief panel shows your answers; fields the assistant chose are marked “decided for you”. Press Edit on any row to change it with the same control the interview used, then Save. Changing the audience, level, length, tone, assessments or language after the outline marks the outline and lessons as out of date (nothing is regenerated until you ask); changing the price or theme does not.

3. Review the outline and the learning objectives

The outline appears as a proposal: modules, lessons with their length, measurable learning objectives and amber citation chips. Select a chip to read the source passage.

• Edit an objective inline, then Approve outline & generate.
• Choose each lesson’s format (see below) before you approve.
• Or write what you want changed and press Request changes; you get a new proposal with the differences marked (added, changed, removed).

Nothing is generated before you approve the outline.

Lesson formats

Every lesson is rich text unless you choose otherwise in the outline. The other formats are only offered when your academy can create them:

Format	What learners get	Offered when
Rich text	Formatted text and a list of the sections it draws on	always
LiaScript	An interactive lesson with two or three questions inside the text that they answer as they read (single choice, multiple choice or a short answer) and see the explanation at once	LiaScript is available (it is by default)
Lesson with an H5P activity	The lesson text followed by one activity: fill in the blanks, drag the words or flash cards	the H5P libraries Blanks, Drag the Words and Dialog Cards are installed
Lesson with an interactive	The lesson text followed by one of the interactive packages in your library, played between the steps the builder picks, with a short cited text beside it	your library holds at least one interactive package

The builder never writes LiaScript, H5P or interactive code. For a LiaScript lesson it writes the questions and our code lays them out in the LiaScript syntax; for an H5P activity it fills a small form of its own (sentences with blanks, words, cards) that our code turns into the H5P content; for an interactive it only chooses a package from your library and the steps. Every question, blank and card cites the passage it comes from, answers have to appear in that passage, and the activity is a diff you approve like every other change. An interactive package is never created or edited by the builder (it is software someone uploaded and answers for).

After the lessons are written you see the extra parts in the lesson preview (Self-check 1, the activity, each with its citations); you can ask the assistant to change a self-check like any other question. You can switch a written lesson back to rich text in the outline editor; the LiaScript document or H5P content is removed when you apply. Another format is written together with the lesson, so choose it in the outline before generating.

4. Watch the lessons being written

The progress card shows the stages (lessons, grounding check, interactive elements, quizzes, metadata) and each lesson with its citations, questions and cost. The running AI cost is shown at the top.

• A grounding check compares every lesson with the passages it cites; claims it cannot find are rewritten once, and anything left is flagged for you.
• If one lesson fails, press Retry on that lesson. The rest of the course is kept.
• You can close the tab; generation continues and the conversation is there when you come back.

5. Apply to your academy

The apply card lists what will be created (course, lessons, topics, quiz questions, landing page) and any warnings. Press Apply to my academy. The course is created unpublished, through the same services the admin uses.

If you picked a theme, the apply writes it to the site settings, but only when you are allowed to change the site (the settings_manage permission). Otherwise the theme is skipped with a note and the course is applied anyway; an admin can pick the theme in Settings.

6. Preview and discuss each element

Press Preview and discuss on the success page (or in the workspace) to see the course the way a learner will, and talk to the assistant about any part of it. The page at /studio/s/<session>/preview shows the same course page, lesson player and landing page learners get, built from the current version of your course, with the chat in a panel on the right (Hide chat collapses it).

• Select an element. Hover a part of the page (the course title, a module, a lesson’s title, a paragraph, a quiz question, a landing section) and press Discuss; with the keyboard, Tab to the Discuss button and press Enter. The element is outlined and the chat is now about it. Esc in the panel, or Back to the preview, returns you to the element.
• See the sources. The panel lists the source passages the element cites; select one to read it.
• Ask, then approve. Type what you want (“make the distractors less obvious”). The proposed change appears in the panel as a diff with its citations. Nothing changes until you press Approve; Reject keeps the current version.
• See it change. After you approve, that element is re-rendered in place and highlighted for a moment, and the course in your academy is updated. Undo and Redo work from the preview too.
• Pages. Switch between the Course page, the Landing page and the Lessons (the lesson player has the program tree, the quizzes and the final test). Quiz questions show the correct answers so you can discuss them.
• Landing sections (headline, outcomes, syllabus, questions) belong to the course: discussing one changes the course title, subtitle or description. Objectives and the FAQ change with the lessons.

The preview never records progress or quiz attempts. The studio’s Preview as learner (below) is the plain page without the chat.

7. Refine any element by chatting

Open the Workspace. Select a lesson or a quiz question in the curriculum tree, then type what you want (“make the distractors less obvious”, “shorter, with an example”). The assistant proposes the change as a diff; Approve applies it to the course, Reject keeps the current version. After you approve, the card reads “Approved; applying to the course…” until the course in your academy has caught up with the approved version, then “Approved and applied”. The Course overview link appears at the same moment.

• Undo and Redo move between versions and update the course.
• Version history lists every version; Restore brings an old one back as a new version.
• Sources (under the tree) lists every section of your sources with how many elements of the course cite it. Sections nothing cites are marked Not cited yet; Show only uncovered sections lists just those, so you can see what the course leaves out. Under a section, Show elements jumps to each lesson, paragraph or question that cites it (an objective jumps to its lesson). When you select an element in the tree, the sections it rests on are highlighted. Select a section’s name to read the passage.

Give me options

Select an element, describe the change and press Give me 2 options (or write “give me options” in the message). The builder makes two proposals, one model call each, so it costs about twice a normal edit (the button says so). They appear side by side as word-level diffs with their citations. Use Option A (or B) approves it and rejects the other; Keep the current text rejects both. Nothing changes until you choose.

Edit the structure

Edit the structure (above the Sources panel) lists modules and lessons. Drag a lesson or module to a new place, or use the buttons: Move up, Move down, Move to previous module, Move to next module (every action has a button, so the keyboard works without dragging). Rename edits the title in place, Remove asks before it deletes, and Add a lesson needs a title, a learning objective and the source section the lesson is based on (a new lesson has no text yet; ask the assistant to write it). A lesson keeps its objectives, citations, text and quiz when you move it. Every change is saved at once as a new version (no approval needed), re-applied to your academy, and can be undone.

8. Preview as a learner

On the success page, Preview as learner opens the course the way learners will see it, even while it is still unpublished: the course page at /preview/courses/<id> and every lesson under it (/preview/courses/<id>/<topic>). A yellow banner says Preview: not published and links back to the studio.

• Only a signed-in author (a tutor of the course, or an admin) can open it. Learners, anonymous visitors and authors of other academies get the normal “not found” page.
• It is a preview, not a learner session: progress is not recorded, Mark as complete is hidden, and quizzes show a note instead of starting an attempt, so nothing is saved.
• The page is private (Cache-Control: private, no-store) and marked noindex.
• Once the course is published, the success page offers View as learner, which goes to the public course page. The preview keeps working and shows Preview: published.

The landing page preview links its call to action to the same preview.

9. Publish

The success page opens with the publish summary: the address the course will have, its price and theme, its size, and two lists.

• Fix before publishing (blocking): the course is not applied yet, the latest version has not been applied, someone edited an element in the admin after the last apply and applying would overwrite it, the generated landing page is not valid, or the course is paid but has no confirmed price. Publish course stays disabled until these are gone.
• Review (warnings): elements without a source citation, lessons flagged by the grounding check, lessons much longer than your brief asked for, an accent colour that had to be adjusted to stay readable, and accessibility problems in the generated text (a heading level that jumps, a link without text, an image without alternative text, a table without a header row). Tick I have read the warnings to publish anyway; the decision is yours.

Publish course publishes the course, shows its generated landing page as the public course page, and for a paid course makes its product purchasable (see Pricing). The page is built from the course’s own content and replaces the standard course page; if it is ever not valid, learners see the standard page. The success page also links to the course form in the admin, the learner preview and the landing preview.

Publish on a new site

Platform operators (people with the platform_admin permission, on an installation that sets TENANCY_NEW_SITES=true) can give a course its own site. Press Edit on the Site row of the Course brief and choose A new site, with a short name (letters, digits and dashes). On the success page, Create the site and move this course then:

1. creates the site (its own database, storage, theme and accounts; this takes a few minutes and the page shows the progress),
2. moves your session to it: the brief, the latest version, your sources and all their passages, so every citation still points to the same passage,
3. creates your account in the new site as an administrator and e-mails you an invitation.

Then Continue in the new site and finish there: apply the course, pick the theme, publish. Nothing is applied or published on the new site before you do, and the course in the original site is not touched. Everyone else publishes into the current site.

10. Keep the course in sync with its sources

Once the course exists, the Sources page (in the left navigation) shows each source of the course: its name and type, how it is connected (Upload, Git repository or Web page), a status (Up to date or New version available), the revision your course reflects (In your course) and the latest one.

• Upload a new version: drop the updated Markdown, PDF or DOCX file on the source. We keep it as a new revision and compare it with the previous one. If the file is the same as the latest revision, nothing is added and you are told so. If the file is rejected, the message says why and nothing changes.
• The revision timeline lists every revision, newest first, with its origin, time, status and what changed (“3 changed, 1 removed, 2 added, 1 moved”). Select a revision to see its changes.
• Each changed passage shows the section, whether it was changed, moved, removed or added, how large the change is and why it may matter (for example “a number changed”), with the old and new text. Removed words are marked with a minus sign and added words with a plus sign, so the difference does not depend on colour.
• Cosmetic changes (spacing, punctuation) are hidden by default; use Show N cosmetic changes to see them.

Uploading a new version does not change your course. The course keeps reading from the revision it reflects until you accept updates.

11. See what is out of date

When a source changes, the course is marked stale until you decide what to do with the change. The marks always use words and an icon, never colour alone:

• In the session list each course shows In sync, Stale · 3 days (how long ago the source changed) or Updates dismissed. Select it to open the update.
• In the workspace a banner at the top says how many elements are out of date and links to the review. In the course tree, lessons and questions carry Update pending, Answer may be wrong or Source removed, and the affected passages are highlighted with a note such as “Based on §3.2 Ratios, changed 3 days ago”.
• Staleness works without AI: it only needs the source to have changed.

12. Review an update

Updates (in the left navigation) lists every update proposal for the course, newest first, with the source revisions it compares, its status, how many elements and quiz answers it touches, how many items you decided, and its cost. Open one to review it. Nothing in the course changes until you accept changes and apply them.

• The source changes are on the left, with the old and new text of every changed passage.
• The proposed changes are in the middle, grouped by lesson. Each item says why it changes, shows the old and new text with removed and added words marked in words as well as colour, and cites the passages it relies on. Accept and Reject are toggle buttons; Undo my decision takes a decision back. After you decide, focus moves to the next undecided item and a screen reader announces the decision.
• Ask for changes lets you write what should be different; the assistant writes a new version of that one element (up to three times per item). Without AI you edit the element in the workspace.
• Warnings are explicit: Possibly unsupported (a claim the source does not back), Answer may be wrong (the source changed where an answer comes from) and Answer changed (the correct answer is different now; learners’ earlier scores stay on record).
• Quiet changes are shown too: Citation update (only the references moved), No change needed (the assistant found nothing to change), Removal (the source no longer covers it), New in the source (a section no lesson covers yet) and Update by hand.
• An item you edited in the workspace after the analysis is marked Conflict or Edited after the analysis. Ask for a new version of it, or reject it.

Accept all accepts every undecided update, removal and no-change item. Reject all keeps your course as it is and marks the new source revision as reviewed, so the same changes are not proposed again; the page asks you to confirm first.

When the estimated AI cost is above the automatic limit, the proposal waits with an Analyse (about $0.42) button and asks you to confirm. While the analysis runs you see its progress per lesson. If a lesson fails, Retry this group runs only that part again. If the AI budget is used up or AI is turned off, the changed elements are listed for you to update by hand in the workspace.

The bar at the bottom shows how many changes are accepted. Apply N accepted changes creates a new version of the course (named “Source update r1 → r2” in the version history) and keeps what learners have done. If you edited elements after the analysis, the apply stops and lists them; if elements were edited in the admin after the last apply, you confirm Overwrite and apply.

13. What learners see after an update

Applying an update never changes what a learner has done: completion, scores and attempts stay as they are, and nobody is graded again. Learners are told what is different:

• a lesson with a major change shows learners who completed or started it “Updated since you completed it” with the note you wrote and a Mark as reviewed button;
• a quiz question whose correct answer changed shows “One question was corrected. Your previous score stays on record. Retake it to update your result.” and gives each learner one extra attempt;
• a removed lesson that a learner had completed stays in their history as “Retired lesson, no longer part of the course”;
• a lesson added after a learner finished the course shows “New since you finished” on the course page, and their course completion is kept.

Optionally the course page can also show “The source of this lesson changed on …; an update is under review”. That marker is off by default.

You see this before you apply, on the review page, in the Learners panel under the summary:

• What learners will see counts the learners each rule reaches, in words (“12 learners will see an “updated since you completed it” notice”, “3 learners get one extra attempt for the corrected question”) and always ends with “Completion and past scores stay as they are.” After the update is applied the same panel is in the past tense.
• Note for learners: what changed is the text under “Updated since you completed it”. It starts as the reasons of the major changes. Edit it (plain text, up to 500 characters; it is never interpreted as formatting) and select Save the note, or Use the suggested note to start again. If you change it and then apply, the note is saved first; if it cannot be saved, nothing is applied.
• Learner notices for this source has two switches, also on the Sources page. Tell learners when a lesson they completed is updated (on by default) controls the “Updated since you completed it”, “New since you finished” and retired-lesson notices; the notice for a corrected quiz question and the extra attempt are always sent. Show that an update is under review (off by default) controls the marker on the course page. A switch is saved as soon as you change it.

14. See who decided what

Audit (in the left navigation) is the trail of everything that happened to the course and its sources: a source was connected or changed, a new revision was found, an update proposal was created, analysed, accepted, rejected or applied, and learner notices were sent. It is written by the system in the same step as the change, it can only grow, and nobody can edit or delete an entry.

• The table shows when, what (in words, with the action code under it), who (a person, the system or an agent) and a one-line summary, newest first, 25 to a page.
• Details on a row opens the full record: the source revision, the course versions it moved between (for example “v3 to v4”), the number of AI calls, what was recorded, and the hash of the entry with the hash of the one before it.
• Filters: an action group (connections, source revisions, update proposals, decisions on changes, learner progress, learner notices), who acted, and a date range. They apply when you select Apply filters; Clear filters shows everything again.
• The bar at the top says Chain verified: N entries checked, none has been changed. Each entry carries a hash of the previous one, so a changed or removed entry breaks the chain. If it does, the bar names the first broken entry and why. Check the chain again repeats the check; it covers the whole academy’s trail, not only this course.
• Export CSV and Export JSON download the trail with the filters you set (all pages, not only the one on screen), for audits and compliance reviews. Spreadsheet cells that would start a formula are neutralised.

15. Connect a repository or web pages

Instead of a file you can follow a Git repository or a set of web pages. The course then keeps reading from the source on its own: a new commit or a changed page becomes a new revision, and the revision becomes a reviewable update (sections 8 to 10). Nothing in the course changes until you approve it.

On New course, next to the upload area, you find Connect a repository and Add web pages.

Connect a repository (GitHub, GitLab, Gitea and Forgejo):

• Where does it live? and, for Gitea, Forgejo and a self-hosted GitLab, the server address (for example https://git.example.com).
• Repository as owner/name. You can paste the address of the repository; we keep the owner/name part.
• Branch: leave it empty for the default branch.
• Folders and files to read: one pattern per line, for example docs/**/*.md. Empty means every Markdown file.
• Access token (optional). Public repositories work without one, but GitHub then allows only 60 requests an hour. A token with read access lifts the limit and opens private repositories. It is stored for the checks and is never shown again: the Sources page only says “Token set” and takes a replacement.

Add web pages: one address per line, up to 20, all on the same site and all starting with https://. The optional main content selector is a CSS selector (for example main or article) for the part of the page to read; without it we read the main content of the page.

Press the button. The form says it is checking, reads the files or pages, shows revision 1 as the source of a new course and continues into the interview as for an uploaded file. If the source is refused, you see the reason as the server gave it (for example that the repository was not found, that no file matches your paths, or that a page address points to a private network) and nothing is created: change the field and try again.

What is checked and when

On the Sources page a connected source shows what it reads from (host, repository and branch, or the pages), its status, when it was last checked and when it is checked next.

• Status is Active, Paused or Error, always as text with an icon. After repeated failures the status shows the last error, for example a branch that no longer exists or a token that expired.
• Check for changes sets the schedule: every hour, every day, every week, or only when you check. Hourly is the fastest schedule; the installation also caps the number of checks per source per day.
• Check now asks for a check at once. The page says the check is queued and refreshes the card and the revision list when it finishes. A paused source has to be resumed first.
• Pause checking stops scheduled checks, webhooks and manual checks until you press Resume checking.
• A check that finds the same content as before adds no revision.

Webhooks (Git)

A webhook lets your Git host tell us at once when someone pushes, so the update does not wait for the next scheduled check. It is optional; the schedule keeps working without it. The connection shows the Webhook URL with a copy button. Create the webhook on your host:

• GitHub: repository Settings, Webhooks, Add webhook. Payload URL: the webhook URL. Content type: application/json. Secret: the webhook secret. Events: Just the push event.
• GitLab: project Settings, Webhooks. URL: the webhook URL. Secret token: the webhook secret. Trigger: Push events.
• Gitea and Forgejo: repository Settings, Webhooks, Add webhook. Target URL: the webhook URL. Content type: application/json. Secret: the webhook secret. Trigger on Push events.

The webhook secret is shown once: right after you connect the repository, and again each time you select Rotate secret. Copy it before you leave the page. Rotating makes the old secret stop working immediately, so the page asks you to confirm and reminds you to update the webhook on your host. Deliveries with a wrong signature are refused, and a burst of pushes is merged into one check (the default wait is ten minutes; an admin can change it).

Limits

• Git: up to 500 files, 1 MB per file and 20 MB in total; up to 20 path patterns. Narrow the paths if the repository is larger.
• Web pages: up to 20 pages of one site, 5 MB per page. Only public https pages that return HTML or text can be read; a page that needs a login, a page on a private network address or a page that redirects to another site is refused.
• An installation can restrict which hosts sources may use. If yours does, the refusal names the allowed hosts.
• Uploaded sources have no schedule and nothing to check: a new version appears when you upload it.

Tips

• Keyboard: every card works with Tab, Space and Enter; new cards take the focus and are announced to screen readers.
• The assistant only writes what your source supports. If you ask for something the source does not cover, it will say so instead of inventing it.
• Each course has an AI budget (USD 5 by default), and the academy has a monthly one. When one is reached the step stops with “Budget reached” and nothing you already have is lost; ask an admin to raise it (settings), then press Retry. The running cost is shown at the top of the workspace.
• If a step fails, Retry repeats only that step.
• Prefer a terminal or an agent? Every step above is also a command, see Build courses from the command line; developers can use the Course Builder API.