Omniscio

LMS (Courses)

Omniscio's learning-management surface, a first-party plugin that ships built into the app: a dashboard for whoever runs a course, editors for courses and lessons, a learner home and lesson viewer with quizzes, and progress tracking with a certificate. It also holds an AI outline generator and an AI build wizard that drafts a whole editable course from a topic or from the builder's own material, both running off the Anthropic key configured in Settings (nothing to set up inside the plugin), and a Docebo importer, which cannot run end to end yet because the Docebo client id and secret are still placeholders.

On this page

What it is

The LMS surface — the team dashboard, the course editor and outline generator, the lesson page editor, the learner home, the lesson reader, the learner progress view, the concepts and glossary screens, the course deck, the catalogue and the library, the Roles and Settings screens, and the Docebo import wizard — is a first-party plugin webview that ships built into the app. Its nineteen screens all exist and all render real content; none is a placeholder.

Where it's headed

The product plan is the Courses PRD (docs/prd-lms.md): who it is for, the decisions on roles, course building, learning and team management, the success measure (90% of a course's flashcards recalled 3 months after finishing), and the build plan — one shared data design, then three parallel tracks (team and cloud, great courses, a joy to use).

The approved content model is built. Learners use answer-free course and lesson readers that strip answer keys and pre-attempt explanations, lesson pages hold blocks of every media kind, and quizzes are graded in main or by the team's server. What is still open is Courses on the phone.

The cloud security rules for team courses are live in the production Firebase project: only a workspace's live full members can see its courses, only owners and admins hand out builder and manager roles, a learner can never edit their own progress, a published course version cannot be rewritten, reminders go out once, and course files are reached only through the server. Team courses use that cloud data today — publishing to a team, pulling a learner's copy, assignments and due dates, notices and reminders, team progress and the public library all travel through it (see Team progress travels through a queue and its neighbours below). A course nobody publishes still stays entirely on this computer.

Where to find it

It is a first-party plugin that ships built into the app (lms is on the built-in-only list, BUILTIN_ONLY_PLUGIN_IDS), so it appears inside the app as its own surface rather than as a separate website. Until 2026-11-12 it was Marketplace-only, and every install ran the old Marketplace build 1.3.1 instead of this source; now the built-in copy always wins, the Marketplace no longer offers Courses, and the old copy's folder (<userData>/plugins/lms, or a renamed lms.stale-*) is removed at the next start, once the built-in copy has loaded, while any data folder in it and every course row are kept. The loader logs which copy it loaded, with both versions. Its screens run from the manager dashboard and the course and lesson editors through to the learner home, lesson viewer and progress view. It appears once Courses is switched on in Settings → Plugins; there is no separate feature switch.

How it behaves

Feature gate

The panel and the command line are gated differently on purpose. The panel loads only while the Courses plugin is enabled. The command line (/lms/*) answers while the plugin is installed, switched on or off, and gives a 403 that names Courses and points to the Marketplace when it is not installed (503 while the plugin system is still starting). The one check is lmsGateRefusal() in src/main/services/lms/lms-feature-gate.ts; there is no separate feature flag. Retired: the pre-plugin lms-panel UnreleasedFeatureId (Decision 4, split-map.md).

Who can do what (roles)

Courses has four roles: learner, course builder, manager and administrator.

  • Your own workspace: you hold all four, so nothing is ever refused.
  • A team workspace: the workspace's owners and admins are Courses administrators, and so also builders and managers. Every other member is a learner, plus builder or manager if an administrator granted it. Guests have no Courses access — not in the team, and not in the app's own workspace either, which is the one grant the personal workspace does not hand back. Nobody can change their own roles, and a grant made before someone left and rejoined does not come back.
  • What each role unlocks: learners take courses, quizzes and decks; builders create and edit courses, concepts, glossary and resources, import, publish and share; managers see team progress, assign courses and nudge; administrators set roles and the workspace's Courses settings.
  • A refusal is plain: "Courses needs you to be a course builder to do that." The command line answers 403 with the same sentence.
  • Without a connection Courses keeps the roles it last saw for the team workspace that is open (or learner if it has never seen it) and checks again a little later. Courses follows the app on which workspace is open: with the app in your own workspace you hold all four, and everything stays on your own computer until a team accepts it. It also asks the cloud about the team your signed-in account belongs to, so a guest is refused rather than handed the personal four — while it can reach that team; a lookup that never got an answer treats you as a learner, never as a full user.

Roles answer at once

Every Courses call checks your roles first, so a slow or unreachable cloud used to hold every screen — even My learning, which reads only this computer — for up to 40 seconds before it could start. Now:

  • A known answer is used straight away. If Courses has seen your roles before (in this session, or saved on this computer from last time), it answers with them at once and checks the cloud in the background. When that check comes back, the very next call uses the new roles, so a promotion or a demotion lands on the next screen you open. A known answer is reused only while the check is still running or the cloud cannot be reached; it never keeps itself alive once the cloud answers.
  • whoAmI no longer waits. Opening a screen starts a fresh check in the background instead of waiting for it.
  • Only the very first lookup waits, and for no longer than one cloud attempt (10 seconds). If the cloud has not answered by then, Courses treats you as a learner until it does.
  • Losing a team sticks. When Courses confirms you have left a team, it drops your saved roles for that team too, and a check that was already running when you left cannot write the old roles back.

Writes are not affected: the local role check only shapes what the screens offer, and the cloud rules decide every team write on their own.

Screens never wait forever

Every screen read has a 30-second limit (LMS_SCREEN_READ_DEADLINE_MS in src/plugins/lms/web/src/lib/read-deadline.ts). A read that has not answered by then fails with "Courses took too long to answer. Try again.", so the screen shows its error message and a Try again button rather than staying on a loading message. The limit covers whoAmI and every list… and get… read, except the four that can legitimately take longer — getMedia, getMediaUrl, getCertificate and getImportStatus. Writes, imports, exports, AI calls and certificate generation have no limit. The reads it covers today: whoAmI, getCourse, listCourses, listModulesByCourse, listLessonsByModule, getEnrollment, listEnrollmentsByCourse, listMyEnrollments, listCompletionsByEnrollment, getManagerDashboardAgg, listCourseLearnerProgress, getLessonPage, getLearnerCourse, getLearnerLessonPage, listQuizAttempts, getTeamQuizTries, listConcepts, getConcept, listResources, listGlossaryTerms, listDeckCards, getCourseDeckStatus, listLmsMembers, getLmsSettings, listWorkspaceCourses, getTeamProgress, getQuizMisses, getCourseRetention, listMyAssignments, listCourseAssignments, getCourseShareLink, listLibraryListings, getLibraryListing and listMyLibraryListings. A new list… or get… read gets the limit automatically.

Screens open without a blank wait

Each Courses screen is its own lazily-loaded chunk, so opening one used to show the loading frame while its code downloaded. The shell now preloads them (lazyNamedViewWithPreload and preloadViewsInIdle in src/plugins/_shared/lazy-view.ts) three at a time in idle time after the panel mounts, so a screen's code is usually already in memory by the time it is opened. A chunk that fails to arrive is retried three times with jittered backoff inside a two-minute budget before the screen reports the failure, so a transient network blip does not become an error page. tests/e2e/ui/lms-screen-load-speed.spec.ts is the end-to-end proof and tests/unit/plugins/lms/lazy-view-preload.test.tsx pins the preload and retry behaviour.

The screens learn your roles from whoAmI; administrators read the member list and set roles through listLmsMembers / setLmsRoles (GET /lms/roles/members, PUT /lms/roles/member/:uid). An administrator sets which managers a learner has with setMemberManagers (PUT /lms/roles/member/:uid/managers): the server checks that each manager is a live member holding the manager role, then updates the learner's role record and every one of their enrollments and assignments, so a removed manager stops seeing that learner everywhere at once. Opening the member list also quietly removes role grants left behind by people who have left the workspace.

The Roles screen

Courses → Admin → Roles is where an administrator hands out the two grantable roles and sets who reports to whom. It shows the workspace's live members and nothing else.

  • Who sees it. A workspace owner or admin gets the member list with a switch for Builder and Manager on every other member. Everyone else gets a plain sentence saying only administrators do this, with no controls and no member list requested at all.
  • What each row shows. An owner or admin is a Courses administrator by virtue of their workspace role, so their row says so and carries no switches; a guest has no Courses access and no switches; every other member is a learner always, with Builder and Manager switchable.
  • Nobody changes their own roles. An administrator's own row cannot be touched, and the server would refuse it anyway.
  • Managers. The managers control on a member's row picks who can see that person's progress; the candidates are the workspace's live managers and administrators. It writes through setMemberManagers, so every one of that person's enrollments and assignments is restamped at once. Someone who has since lost the manager role or left the workspace is no longer offered, and saving drops them from that person's list rather than sending an entry the server would refuse.
  • The list is live. Opening it quietly removes grants left by people who have left, and a member who leaves while the screen is open is refused with a plain sentence and a Refresh.
  • Your own workspace. In the personal workspace Courses has no team to manage, so the screen says roles need a team workspace and asks the cloud for nothing.
  • The screen is convenience, never the guard. Every change is checked again in main against the caller's role and against the workspace the screen was showing, and the cloud rules decide it a third time.

The Reminders settings

Courses → Settings → Reminders holds the two workspace settings the reminder run reads: the escalation grace period (escalationGraceDays, a whole number of days from 1 to 30, default 3) and whether reminder emails go out at all (reminderEmail, default on).

  • Who reads and who changes. Any member sees the saved values; only a workspace administrator gets a Save button or a live email switch, and main refuses a write from anyone else before the cloud is asked. The screen reads through getLmsSettings and writes through updateLmsSettings, which returns the saved settings so the screen shows what the workspace accepted rather than what it hoped for.
  • What the grace period means. A learner is reminded first. Their manager hears only once the due date has passed by this many days, counted from the learner's first recorded reminder — the run reads the number fresh each morning, and an unreadable settings document still means no escalation rather than a guessed one.
  • The personal workspace. Nobody assigns a course outside a team, so the section says reminders are for team courses and asks the cloud for nothing.
  • The workspace is pinned. The write carries the workspace the screen was showing, so switching workspaces mid-edit is refused in main instead of changing another team's settings.

AI spending

The seven methods that spend AI money — generateOutline, doceboAiReview, proposeDeckCards, rewriteBlock, the course builder’s proposeCourseFromTopic and proposeCourseFromMaterial, and the AI helper’s helperAsk — sit behind the plugin’s ai permission and stay reserved to the Courses plugin, so the consent screen's AI grant is the switch and no other plugin can reach them. They share the host's per-plugin daily AI cap (pluginAiDailyCostCapUsd, the same $5 default as any other plugin): before a call, main sums every ledger label these paths bill and refuses with the cap sentence when today's spend has reached it. The check is in the services, so the agent command line inherits it too. The panel shows that sentence in its degraded empty state. The outline's output ceiling is sized to fit a maximum-length outline plus the model's own thinking, so a long course is not cut off mid-JSON. Suggesting lesson cards bills its own label, lms:deck-cards, which the cap reads along with the rest, and a lesson too short to carry cards never costs a call at all. The AI helper bills lms:helper, which the cap reads too, and a question about a live quiz never costs a call. The course builder bills its lesson drafts under lms:course-builder, which the cap reads alongside the others, and it checks the cap again before every lesson it drafts, so a draft that reaches the cap part-way keeps what it already wrote.

Not wired. omniscio://lms/* was never completed when the LMS moved into a plugin: main's deep-link parsers have no lms handling, nothing emits the lms:route push kind, and the plugin's lms-route-resolver.ts was imported by nothing. Both have been removed. Re-declare the push kind only alongside the main-side emitter that pushes it and the plugin subscriber that consumes it.

Keyboard shortcuts

Every command key in Courses resolves from ONE registry in the plugin — src/plugins/lms/web/src/lib/shortcut-registry.ts — and never from a hand-written key check. A command is { id, label, labelKey, scope, defaultBindings, inEditor? }; scope is global or one of the screen kinds the rest of the plugin already uses, so a screen's keys exist only while that screen is open. A command may carry several keys (Search has Ctrl+K and /), and an empty list is the explicit "disabled" state.

  • Rebinding happens in Courses → Settings → Keyboard shortcuts. ? opens the same list as an overlay: this screen's keys first, then the ones that work everywhere, with an "All screens" view and a "Customize…" button that goes to Settings.
  • A binding is refused when it is structural (Escape, Tab, the arrow keys), when another command whose scope overlaps already uses it (a global command overlaps every screen, and a bare key that is another binding's chord prefix counts, in either direction), or when Omniscio or the operating system owns it. The refusal names the reason. Removing a binding and Reset always work, even when the reserved list could not be read — only a NEW key is refused in that case. Main refuses a reserved key on save too, so the guard does not depend on the screen.
  • The reserved set is computed in main on every save — prefsSet refuses a reserved shortcutBindings value outright — and the Settings screen re-reads the set before each save, so a host hotkey changed in another panel cannot be accepted against a stale list. Nothing is listed by hand: the chords a webview guest hands back (derived from the forwarder's own predicate), the current bindings of the app's reserved global-nav actions and of the action that closes a panel, the OS/Electron list, the main window's own key, and the app's live system-wide hotkeys.
  • Storage is per person in the app database (lms_prefs, added by F3), not localStorage and not plugin storage.kv, so it survives a reinstall. Two scopes: person (bindings, the glossary-marks switch) and person-in-a-workspace (recents, last view, outline-rail state). prefsGet returns null for a key never written; the defaults live in the registry, not in the database.
  • The dispatcher (components/shortcuts/use-lms-keyboard.ts) matches exact modifiers, reads a shifted punctuation key by the character it produces (so ? is Shift+/), only fires an inEditor command while the person is typing, and stands down while an open dialog, the help overlay or a key capture owns the keyboard. It ignores a key typed mid-composition and an auto-repeat except on the movement keys, and a two-key chord is cancelled by Escape, a modifier, blur or 1.2 seconds. While a chord prefix is pending the shell announces it with a trailing ellipsis (G…) through the polite live region, so a person who cannot see the keyboard never hears a bare letter and wonders what it did.
  • A screen’s wired commands are also what the Ctrl+K box can run. The same handlers map a screen hands the dispatcher registers into a small per-screen registry (store/use-lms-command-registry-store.ts, fed by components/shortcuts/use-scoped-shortcuts.ts and use-screen-commands.ts): register on mount, unregister on unmount, one row per command id even when two components of one screen wire it. The box (C6) reads that registry, filters it by the person’s roles (a screen passes BUILDER_ROLES / MANAGER_ROLES where its commands are role-limited; no list means anyone on that screen may run it), and takes every label and key cap from this registry and the resolved bindings — there is no second key map. A screen whose command is not on the dispatcher (the AI build wizard’s Save) calls useScreenCommands itself.
  • A binding can be allowed inside a text field on its own. A command marked inEditor runs while the person is typing and is expected to prevent the key; a command that lists inEditorBindings runs only for those bindings there. Search lists Ctrl+K and not /, so the box opens from a filter while a bare / still types.
  • Which commands are wired today: ?, the nine "go to" commands, Settings, Search (C6 — the box in the next section), the helper (Ctrl+/ / Ctrl+J, C9 — the panel in its own section below), U / B / [ from the breadcrumb bar, the AI build wizard's save, and both builder screens — the Course editor (J/K move the selected row, Enter opens it or expands a module, A opens that module's Add-lesson menu, Shift+A adds a module, Alt+Shift+ArrowUp/Down moves the row, Alt+Ctrl+Enter previews the lesson) and the Lesson editor (Ctrl+S saves, Alt+Ctrl+Enter previews, Alt+Shift+ArrowUp/Down moves the focused page block, and B3's formatting keys). The preview is a read-only sheet rendering the lesson through the learner page viewer, so a quiz shows its questions without grading. On the learner side the lesson page wires N / P (next and previous lesson), R (jump to the resources panel), D (terms on the page), and Enter to complete the lesson and continue, and the course overview wires Enter (continue with the lesson shown under "Up next"); U, B and [ come from the breadcrumb bar. The two learner lists use one shared hook (components/shortcuts/use-lms-list-keys.ts): J / K come from the registry (learner-home.next / .prev on My learning, catalog.next / .prev on Workspace courses), the arrow keys and Home / End move through the same rows as structural keys because a person expects them there, and Enter opens the focused row — a course card on My learning, an enrolled card on Workspace courses. The keys walk the rows in the order the screen shows them, which on My learning is the newest enrollment first (listEnrollmentsByUser orders by enrolled_at down), so a test that seeds two courses must read the first row from the screen rather than assume its own seeding order. F focuses the Workspace courses filter box and does nothing on My learning, which has no filter; Enter on a card the person is not enrolled in does nothing, so walking a list can never sign anyone up.
  • The manager, library and admin screens own the same two roles. Each is a list of rows the shared hook walks with J / K (plus the arrow keys and Home / End), F focuses the filter that screen actually has, and Enter runs the row's own action. The Library walks its listing cards and Enter opens one. The manager dashboard walks the team progress rows and Enter opens that row's course in the per-course view; in the personal workspace it walks the Active courses cards instead, opens the same per-course view, and F does nothing because that rollup has no filter. A opens Assign course on the team dashboard. The per-course table walks its learner rows (its rows have no Enter action) and F focuses its progress filter group; the team variant's three detail tabs are 1 / 2 / 3. Roles walks the member rows and Enter opens that member's managers dialog; it gained the filter box those keys focus, which narrows the list by display name or uid and says so when nothing matches.
  • A tooltip shows the cap. Every control a command duplicates carries that command's key in its title, read live from the person's bindings: the Library and Roles search boxes (F), the team member select (F), Assign course (A) and the three detail tabs (1–3). A registered command with no handler does nothing, and the dispatcher takes a key only when a handler will run it.
  • The selection menu's key is structural, not a Courses command. Shift+F10 and the Menu key are the operating system's context-menu keys: the browser delivers them as the same contextmenu event a right-click produces, so they are not in the registry, cannot be rebound, and do not appear in the shortcuts list as a bindable row. They reach the builder preview too, where the dispatcher stands down behind an open dialog — which is exactly why the menu does not ride the registry.

The breadcrumb and the course outline rail

Every screen in Courses except the lesson reader carries a breadcrumb bar, drawn once by the plugin shell (App.tsx) rather than by each screen, so a new screen inherits it. The trail follows where the item lives: a lesson reads My learning › Course › Module › Lesson for a learner and Courses › Course › Module › Lesson for a builder, a course concept reads Courses › Course › Concepts › Concept for a builder and My learning › Course › Concept for a learner, and a workspace concept reads Concepts › Concept. Every crumb but the last is a button that opens that level's own screen; a crumb with no screen of its own (a module, the Admin section, a learner's course on a concept) is plain text, and the last is plain text with aria-current="page". A trail longer than the bar holds folds its middle into a "…" menu (on a narrow window that is anything past the first and last crumb) and always shows the first and last. A concept opened from a lesson adds a "Back to ‹lesson›" button beside the trail.

  • U goes up one level — the nearest crumb above that has a screen of its own, so U from a lesson lands on the course overview. At a top level (My learning, Courses, Library, …) it does nothing and says so in a polite live region. B goes back through Courses' own view history, which the shell records as the person navigates; at the start of that history it says the same thing. Both come from the same registry every other key does, so they are rebindable in Settings.
  • The course outline rail sits in the shell's right slot on every course screen — course overview, course concept, course editor, lesson editor and course deck — and lists the course's modules and lessons with a done mark, the current item highlighted, the lesson's reading minutes, and a "Must pass" marker in the needs-you colour on a lesson whose quiz must be passed. It reads only the reads the screens already use: the learner course reader (with the enrollment's completions and its quiz statuses) for a learner, and the course tree for a builder (the rail asks for it only where its screen does not already). Arrow keys move focus between the lessons you can SEE, Enter opens the focused one, and [ collapses or expands the whole rail. A collapsed rail is remembered per person in the outlineRail pref ({ collapsed }), and on a narrow window the rail becomes a dialog sheet opened by the same [ or by the bar's Outline button. An empty course says "No lessons yet", with an "Add a lesson" button for a builder or admin; a course whose tree is still loading says so, and a failed read shows the plain reason without blocking the screen.
  • The lesson reader is the one screen without a breadcrumb or a standing rail. It shows the lesson: a slim bar, the module line and the lesson title, the reading, the resources panel, and the finish row last. The bar's Up button names the course it returns to, its middle control reads "Lesson N of M" over a mini progress bar and opens the outline as a SHEET at any width, and its helper button opens the helper panel; each carries its own key in a tooltip. That middle control also carries the word Outline as its name for anyone who cannot see the pill's chevron — a learner with no other route to another lesson must be able to find it — and it reads "Course outline" outright when the lesson's place in the course is not known yet. The sheet is where an outline folds: it carries a "N of M done" progress header, opens only the module holding the lesson you are reading (the rest are one line with their lesson count and unfold on a click), and keeps its arrow keys inside the unfolded lessons. Every other screen keeps every module open.
  • What the bar carries, and what it does not: three controls — the Up button naming the course, the "Lesson N of M" outline toggle, and the helper button. There is still no Search button: the Ctrl+K box (C6) is reached by its own key, so the bar does not ship a dead control for it.

How Courses looks

Courses is a separate webview, so it cannot use the app's own styles. It reads the theme the app injects (surface scale, accent, status colours, the deepened --btn-accent-fill and --on-accent-color), mapped in web/src/index.css, and follows light, dark and every accent with no CSS of its own per theme.

  • One canvas. Pages paint surface-50 over the theme's own two-colour wash (the host's --app-glow-1 / --app-glow-2 as two static radial gradients on .lms-scope — no blur filter, so it rasterises once). The sidebar, breadcrumb bar and rails paint surface-100.

  • Glass where the theme is glass. The learner surfaces that read as panels — the lesson bar, the extras list and its rows, the resources panel, the resume card, the other-courses list and its rows — paint the host's own panel tokens (--panel-bg, --panel-bg-hover and the hairline --panel-border-color, mapped to bg-panel / bg-panel-hover / border-panel-line), so Courses looks like part of Omniscio in Glassmorphism and goes flat with a flat theme. A theme with no wash sends transparent, so switching themes never leaves an old glow painted.

  • Extras read as one list. A lesson's concept cards, key terms and link cards are one line each in a single list (ui/DisclosureRow), and a line unfolds in place to the definition, the summary or the description it was hiding — a link line with no description is a direct link to the page instead. Only runs of consecutive extras group: a paragraph between two of them still splits them, and a lone extra still gets a list rather than a bare row.

  • One page header. Every Courses screen opens with ui/PageHeader: a neutral icon tile, an h1 title, an optional subtitle and the screen's actions, with any Back button first among the actions. Each screen has one accent-filled action at most. The header carries data-ui="page-header", which is how a test proves a screen uses it; it changes nothing on screen.

  • A small kit in web/src/ui/. PageHeader, PageBody (reading, default and wide widths), Section (sentence-case title plus count), Chip (neutral, accent, success, warning, danger), ProgressBar (accessible, success colour at 100%), StatTile and CourseTile (a neutral cover band with the course initial, title, progress and meta, as one button). ui/Button builds on the shared plugin button and adds a card variant for multi-line clickable cards. ui/SearchInput is the filter box: type="search" earns the searchbox role, so the UA's own ::-webkit-search-cancel-button is suppressed in the class list to keep a single clear button (the kit's X) instead of two. It takes an optional inputRef, which is how a screen's filter key puts the cursor in the box.

  • Done is green. Completion and success use the host's status-agent. The host's ready colour (status-ready) is cyan, so Courses never uses it — the Docebo importer included.

  • Three guards keep it working. tests/unit/plugins/lms/lms-css-tokens-and-scan-roots.test.ts fails when the stylesheet stops scanning a sibling plugin folder Courses imports UI from. Without that scan, the shared button's height, padding and focus ring emitted no CSS at all. The same test fails when a colour class names a token index.css does not define. status-alert, status-attention and surface-0 used to paint nothing. It also fails on any colour literal in the Courses source — a hex, an rgb(), a Tailwind palette class, a bare white/black ink or an arbitrary value — except the var(--token, #hex) fallbacks in index.css, the named scrim and shadow constants in web/src/ui/styles.ts, and web/src/lib/appearance.ts, the one module that computes a colour a person chose. A positive control proves the test can fail.

Choosing a Courses accent

Courses follows the app's theme, and Settings carries one choice of its own: Appearance.

  • Follow your Omniscio theme is the default and changes nothing. Surfaces, text, fonts, the text size and the accent all come from the app.
  • A person may instead pick one of seven presets, or type a hex colour. Courses then re-derives its accent, its button fill and its button label from that colour, using the app's own accent functions (shared in src/shared/accent-contrast.ts), so a pale colour gets the same deepened fill and readable label the app's own buttons get.
  • The choice is written on the Courses panel's own wrapper, never on the document root — the root carries the app's values — so clearing it restores the app's accent exactly and the rest of the app never changes.
  • It is a per-person preference (lms_prefs, key appearance), stored like the shortcut bindings, and cached in the panel's own storage so the first frame after a reload already wears it.
  • The end-to-end proof is tests/e2e/ui/lms-courses-theme.spec.ts: Courses mounted in one theme, flipped to the other live with its marker intact, then given an accent while the app's own accent is asserted unchanged.

Every Courses screen is on this look: the sidebar, breadcrumbs and outline rail, the Courses list, My learning, Workspace courses, the course editor, both dashboards, Library and a Library course page, Concepts and a single concept, Glossary, Roles, Settings, the lesson page editor, the learner progress view, the course deck, the AI build wizard and the Docebo import wizard, and the overlays (the right-click selection menu and its card dialog, the define pill, terms on this page, the glossary term popover, the outline drawer, and the certificate and bulk-nudge dialogs). tests/unit/plugins/lms/lms-courses-restyle-scan.test.ts keeps the screens restyled in H-10556 there: it fails when one of them gains a hand-rolled <button> or the cyan ready colour, or a screen stops importing ui/PageHeader, and a positive control proves it can fail. tests/e2e/ui/lms-courses-restyle.spec.ts opens the lesson page editor, the course deck, a concept, the AI build wizard and the import wizard and checks each wears the kit header.

The AI helper panel

Ctrl+/ or Ctrl+J opens a helper beside the screen you are on, from every Courses screen, and the same keys close it again — including while you are typing in its box, because the registry marks the command inEditor. It takes the shell's right slot, so the course outline rail folds away while it is open and comes back when it closes. Focus moves to the question box on open and returns to what you were looking at when the panel closes, and Escape closes it.

  • What it answers from. The panel sends the question and the ids of the lesson you are reading (or the course or concept, on those screens) and nothing else — no lesson text, no quiz choices, no answer keys. Main builds the context, so the panel can never show a quiz answer it was not given. This is the only AI door inside the Courses screen: the panel calls the same helperAsk a command line does. Taking a whole course through to done is the Sessions tab below.
  • Where it can answer. helperAsk answers about a lesson, about a whole course, or about the person's whole workspace, and the panel asks on every Courses screen. One rule picks the scope from the ids the screen can give: a lesson id asks about that lesson (a learner's lesson reader, a builder's lesson editor), a course id asks about that course (the course editor, Course deck, a course's Concepts and Glossary, My learning, and the manager's per-course table), and a screen with neither asks about the workspace — the courses list, My learning home, the manager dashboard, the import wizard, the catalog, the Library and a Library item, a concept, the course builder, Roles and Settings. The panel's second line says which of the three it is answering from, and on a workspace ask it always says "your whole workspace" rather than echoing a course name the answer will not use. A course-wide answer comes from the course's outline — module and lesson titles with a short excerpt of each lesson — never from every page body. A lesson or course id you cannot read — another team's course, or a course on this computer you neither own nor are enrolled in — is refused as forbidden before anything is read, so sending an id is never the same as being allowed to open it.
  • What a workspace answer is drawn from. Every course the person may read — the same reach the LMS opens a course's own Glossary and Concepts with, so a team member reaches the team's courses and a manager is not left with their own few — most recently updated first, capped at 20 courses. Each contributes its title and a short description, and its module and lesson titles with a short excerpt, dealt round-robin across the courses so one long course cannot take the whole outline; then the workspace glossary and workspace concepts. A course's own term is listed labelled with its course (Policy (Cells): …) beside the workspace's own, so two courses defining one word both appear instead of one silently winning. The whole thing stays inside the one 12,000-character budget, filled section by section against a running total with room held back for the glossary and concepts so the outline cannot take them, and each line clamped as a whole; a selection is cut at 800 characters there. The sources under an answer are exactly the material the model was given, never an item a budget cut afterwards. A person with nothing readable yet is told plainly there is nothing to answer from, and nothing is spent.
  • What an answer looks like. The words, then the sources it came from as links that open that lesson, concept or term in Courses. A learner is always sent to the learner's own lesson and course screens; a lesson or course source only opens an editor for someone who can build, and a person who cannot build sees the source as plain text instead of a link. C8's finished sentences are shown as they arrive: a decline while a quiz is live ("I cannot help with a quiz you have not finished yet"), no AI key, the daily cap, and an unreachable service each read as a plain sentence rather than a failure. A question that could not be sent at all shows one humanised line with "Try again".
  • What it can do. Below the conversation is what you can run, drawn from the same command registry the keys come from, filtered to your role — a learner is never offered the builder or admin destinations. Going anywhere or opening Search or the shortcuts runs immediately. Anything that changes something (today, the glossary-marks switch) opens a confirm card naming the action, and nothing changes until you press "Run it"; Cancel changes nothing. Nothing runs from text the helper read in a course, and the panel has no way to submit a quiz or complete a lesson.
  • The conversation lasts while the panel is open for one course and is not saved. It starts again on sign-out and when you move to another course.

The Sessions tab

The two halves of Courses — Courses, the screen you are on, and Sessions, the real AI sessions that belong to Courses — are switched from the top of the Courses sidebar, with the sidebar's own list underneath, the way a Mind Map or the Messages surface does it. Nothing spans the top of the screen. The sessions themselves come from the app's one shared sessions list rather than a copy of it, and a session started here shows up in that list the way it does anywhere else. The app owns which half is showing: the switch asks it (through the plugin bridge's host.setSurfaceTab) and follows whatever it answers, so opening a chat and picking Courses can never leave the two disagreeing.

  • Starting one. On the Sessions tab, "New session" starts a working session right there, or take one of the four starters: draft a course on a topic, see where you are in your courses, write the next lesson, or find who is falling behind.
  • What it already knows. A session started here opens knowing it is working in Courses and how to drive it: read and build courses, modules and lessons; draft an outline from a topic; check who has finished what; enrol someone or send a reminder; and reach the course's concepts and glossary. It is told to read before it writes, never to delete anything you did not name, and that only an admin can change a course.
  • Where it works. A session opens as an ordinary chat in place of the Courses screen, and the switch stays on the sidebar while a chat has the screen, so picking Courses brings the screen straight back.
  • What it is not. It is not the Ctrl+/ helper above. That one answers a question about the lesson you have open and nothing else; this one is the general session that can take a course end to end.

The import wizard, the outline drawer and the certificate dialog

  • The Docebo import wizard is four steps under one header. Pick source, Preview and select, AI review, Import progress. Back and Continue sit in its footer; the close button asks before cancelling a job that is still running. Reopening the wizard while the store still holds a job (an app restart mid-import) reads its status and jumps straight to step 4, so the person re-attaches to the live import.
  • Step 2 lists the tenant's courses. The person filters (All / Published), searches, selects all, clears, or picks courses one by one; past 100 filtered rows the list is virtualized.
  • Step 3 is the AI review. It asks doceboAiReview once on arrival, with a 60-second limit held in the store, and shows title rewrites and type mappings as cards a person accepts or edits; a mapping that needs a person is marked in the warning tone. An empty answer and an unavailable review each have their own plain copy, and the step can be skipped.
  • Step 4 starts the import once and follows it. startImport is guarded so a re-render never starts a second job, and the store polls getImportStatus every two seconds until the job reaches complete, failed or cancelled, each with its own page. Each course's status shows as a chip with its full label.
  • The outline drawer shows an AI outline proposal in one of six states — loading, loaded, no title yet, no AI key, error, or accepting. Accepting the whole outline writes it in one batch through the store and closes; a partial failure is kept as lastPartialFailure, which the course editor shows as a banner the builder can dismiss.
  • The certificate dialog opens from the certificate button: an inline preview of the PDF (the shared PdfViewer), a Download button and the LinkedIn share button. The store owns the request for a course and person and keeps the issued certificate.
  • A bulk nudge asks first. Nudging many learners sends each one an inbox notice, so the action goes through the confirm dialog before anything is sent.

Known gaps

  • Docebo sign-in: the app's Docebo client id and secret resolve to the placeholders YOUR_DOCEBO_CLIENT_ID and YOUR_DOCEBO_CLIENT_SECRET unless they are set in the environment, and no settings screen writes the secret, so the import cannot sign in to Docebo in the version that ships today (src/main/services/lms/docebo/docebo-auth-service.ts). The owner has decided it stays as it is.

  • Push subscribers: the plugin webview does not yet subscribe to the host's push kinds; the Docebo import wizard polls getImportStatus every two seconds while a job is running instead.

  • i18n keys: every user-facing string is authored with a key + English fallback, and rendererT (src/plugins/lms/web/src/lib/i18n.ts) runs on the shared plugin loader, rendering src/plugins/lms/web/locales/<code>.json for the host's UI language and falling back to the English at the call site. Spanish ships today; another language is one catalog file.

  • Certificate URL: the PDF lives on-disk in the user's userData folder (not a public URL LinkedIn can crawl); the LinkedIn share URL therefore omits certUrl.

  • Courses on the phone: the plugin's manifest carries no mobile entry, so the phone app does not admit it yet.

Notable adaptations from the ref (do NOT re-open without splitting the design)

Locked at GATE 1 (Session 1); details in _kb/kickoffs/lms/split-map.md:

  1. Reading A — author the plugin webview fresh from the ref, not port-then-delete. src/renderer/src/features/lms/ never existed on this branch.
  2. Push wiring approach 1 — plugin-scoped IPC channels via webContents.send (matches plugin-session-status-change), not IPC channel additions.
  3. UI primitives — plugin owns its own primitives under src/plugins/lms/web/src/ui/** (Writer's 8 base + 4 LMS-specific + Session 2's 4 additions + Session 3's Modal/DialogShell extras). The plugin webview cannot import from the renderer kit.
  4. DirectionalIcon dropped across every ported component — the plugin has no right-to-left layout work yet, so raw lucide icons work.
  5. data-ui-anchor props dropped across every ported component — the plugin webview is an isolated React tree the anchor registry cannot see across.

The v2 surface is registered before it is built

Courses' surface was registered in one change so that no later task had to edit a shared file to add a method. Every method exists on all five faces at once — the bridge switch, the argument tuples, the preload surface, the webview wrapper and the command line — and each one forwards to a function in its own folder under src/main/services/lms/<feature>/. All 116 of them answer real data today; nothing is left as a stub.

What that means when you use it:

  • A team change carries the workspace the screen was showing. Publishing a course to a workspace, retiring one, pulling one, assigning, reminding, setting roles or managers, changing the workspace's reminder settings, sharing, and anything on the public library all send the workspace the screen rendered. If the app has since switched to a different workspace, main refuses the write and says so, instead of applying it to the wrong team. Courses shows you that message rather than a generic failure. A change that stays on your own machine — writing a course, a lesson, a card — is not affected.
  • A library listing copies into a local draft, never straight into a team course, and a team course is retired rather than deleted, so the history of everyone who took it survives.
  • An unrecognised operation answers a named error rather than an empty value, so "nobody has written this" is never mistaken for "nothing there". Nothing is unbuilt today.
  • The routes that spend money (the AI helpers) or read files and fetch web pages take the command-line key only; a plugin credential is refused there.
  • Lessons are now pages or legacy documents. A lesson that already holds a page can no longer be saved as a plain document — that would silently drop every block it holds — while a lesson whose stored content cannot be read at all can still be replaced.
  • Finishing a lesson goes through one shared path: an already-recorded completion is returned unchanged, and a lesson with a quiz finishes only once each quiz meets its rule (see Quizzes below). Any score the screen sends for a quiz lesson is ignored.
  • The learner now reads a page lesson in a page viewer. The lesson screen checks the stored format before the lesson type: a page shows its blocks in order, a text block rendered as sanitized markdown, and every other block kind has a slot that arrives with its own wave task. A block type this build does not know, or one whose content it cannot read, shows a plain "This content isn't supported yet" card, and one block failing never hides the blocks around it. A picture is read through the lesson that holds it and drawn with its description and caption; a picture that cannot be read at all shows a plain card carrying that description, so the meaning of the picture survives even when the file does not. A damaged block already stored on this computer is still refused a step earlier by the lesson read, so a course stops unloading only once the lesson read tolerates a damaged row — a step this build has not taken yet.
  • A lesson that is one media item fills the width. A page whose only block is a picture, a video, a PDF, an audio file or a file attachment is shown full-width with the course outline still beside it, so a "watch this" or "look at this diagram" lesson is the item and nothing else. A media item with any other block on the page — even one line of text — keeps the normal reading column, and so does a page of text, a quiz, a link card or an empty page. The shape is worked out from the blocks every time the lesson opens and is never stored, so nothing has to be marked: a lesson gains the layout the moment its page is one media item. A media kind whose viewer has not arrived yet shows the usual safe card, at full width.
  • Old document lessons now open as pages. An existing document lesson is read as a page holding its whole text in one block, converted when it is read, so nothing stored changes until the builder saves it. A document the block editor cannot keep stays in the older document editor, where it is still fully editable: a table (with or without outer pipes), a picture, a checklist, raw HTML, an HTML comment or entity, a reference-style link, a link written bare or in angle brackets, or a document larger than the page size limits. That means a lesson imported from Docebo, whose text is stored as HTML, keeps its current editor. Video lessons keep the screen they have today until their own task.
  • A quiz still lists as a quiz. An existing quiz lesson is read as a page holding one quiz block, but the course tree and the lesson list name it a Quiz and draw the quiz badge rather than a page's — in the builder's editor, in the outline drawer and on the command line. The same holds after the builder saves that quiz in the page editor: the saved row is a page, and the read still answers quiz. A page that holds a text block alongside its quiz is a page, and reads as one.

Ingesting a recording as course material

A course builder can hand Courses a link to an audio or video recording and get its transcript back as material for building a course. The transcription runs on this computer, so the recording is read here and never uploaded anywhere.

  • A public https link only. A plain http:// link, an address on this computer or on a private network, a page that is not a recording, and a link whose path is not an audio or video file are each refused in plain words before anything is downloaded.
  • Six formats: MP3, M4A, WAV and OGG for audio, MP4 and WEBM for video. Anything else is refused naming the kinds it takes.
  • 100 MB at most, the same ceiling the course media store uses. A recording over it is refused with a sentence naming the limit rather than half-read, and one that trips the ceiling partway through a download is refused the same way and its part-file removed.
  • A recording with no speech is refused, not filled in: "Courses did not find any speech in that recording." A placeholder line never becomes course material.
  • The transcript is held to 200,000 characters — the same limit a text block and an audio block's transcript carry.
  • Builders only. A learner is refused with the same sentence every builder-only action gives.
  • A link is fetched once, safely and briefly. Redirects are followed only to other public addresses, the address is re-checked at connect time so a public link cannot be bounced onto this computer's own network, a download gets five minutes, and the temporary copy is deleted whether the transcription succeeds, fails or finds no speech.
  • The panel calls it when AI course building arrives. Until that wizard ships, this answers on the Courses command line (POST /lms/ingest), which takes the full-trust key: {"sources":[{"kind":"url","url":"https://…/lecture.mp3"}]} answers {"sources":[{"name":"lecture.mp3","kind":"audio","text":"…"}],"failures":[]}. A web page or a YouTube link in the batch is read by its own reader, below, and a document path in the batch is read by the document reader, under Bringing your own documents into a course.

Reading a web page or a YouTube video as course material

A course builder can hand Courses a link to a page or a YouTube video and get its text back as material for building a course, read here on this computer.

  • A web page is read as an article. The page's navigation, headers, footers and ad slots are dropped and what a reader would have read is kept; a page that is not an article falls back to the page's own text. Long material is cut at a paragraph boundary, never mid-sentence, at the 200,000-character ceiling a text block carries.
  • A YouTube link is read as its captions, one timed line each ([1:23] …), and the video's own title names the material. The short youtu.be/…, youtube.com/shorts/… and /embed/… shapes are turned into the video they name first, and the caption address the page hands back is checked against YouTube's own hosts before anything is fetched from it. A video with no captions is refused rather than guessed at.
  • A public https link only. A plain http:// link, an address on this computer or on a private network, and an address that is not a web page (a PDF, a zip) are each refused in plain words before anything is fetched.
  • A link is fetched once, safely and briefly. Redirects are followed only to other public addresses and the address is re-checked at connect time, so a public link cannot be bounced onto this computer's own network. At most 10 MB is read and a fetch gets fifteen seconds.
  • Each refusal says which one it was. A refused address, a page with nothing to read, a video without captions: each carries its own reason beside the status, so the screen can say the specific thing instead of "something went wrong".
  • Builders only. A learner is refused with the same sentence every builder-only action gives, before anything is fetched.
  • The panel calls it when AI course building arrives, through the same POST /lms/ingest shown above: {"sources":[{"kind":"url","url":"https://example.com/lesson"}]} answers {"sources":[{"name":"How cells divide","kind":"web-page","text":"…"}]}, and a YouTube link answers with "kind":"youtube".

Every planned screen is on the rail, and every one is built

The same move F5 made for the backend, made for the panel: all nineteen screens exist in their own files, so a task that builds one edits nothing shared. Every one of them renders real content today; none is a placeholder.

  • The sidebar has four groups — Learn, Build, Team and Admin — with Settings at the foot. Every screen the older six-tab rail reached is still reachable.
  • Only the screens that appear in the sidebar have a rail row; the rest open from their parent — a library course from the Library, a concept from Concepts or a lesson, the course deck from the course editor.
  • The share, publish and report surfaces are dialogs rather than screens. Publishing, the share link and the library's report dialog are all built (below). The share-link page itself is served by Shares, outside the plugin.
  • A screen's controls follow the person's role, one screen at a time. Main refuses every action a role does not cover and whoAmI reports the real roles. The Roles screen is the first to hide its own controls (below); the rest still show theirs, which is convenience rather than protection — nothing behind them is allowed. A member of a team workspace who holds no Courses role at all reads a plain panel telling them to ask a workspace admin, instead of an empty shell.

Team progress travels through a queue

A learner's progress on a team course reaches the workspace through the server, never by the app writing it directly, so a manager sees real, server-graded results.

  • Enrolling, finishing a lesson and retention fill the queue. A learner's self-enrolment in a workspace course queues one enrol update carrying the course version the pull named, and every finished lesson queues one complete-lesson update naming the published lesson version it was read from, so a manager sees it once the queue is sent. Retention queues its own (below). A quiz attempt is the exception: it goes to the server at once, because the learner needs the grade before finishing the lesson (see Quizzes).
  • A learner's lasting memory is measured on their own computer and sent as one snapshot. The figure is the mean of the FSRS forgetting curve over that course's cards sitting in the learner's own deck, projected at three months after they finished the course — or at today once that date has passed, so a date in the past is never projected (that would read 100% for every card reviewed since). It is learner-asserted and feeds only the memory view: it never blocks a lesson, a quiz or a certificate. The snapshot carries {at, recall, cards}, is refreshed on the learner's own view — the read completes that refresh before it answers, and logs a failure rather than failing the view — and after a lesson completes, and is queued at most once an hour per course under retention:<course>:<hour>; a later number inside that hour waits for the next one. The id is bucketed because an unchanged id is dropped by the queue and answered duplicate by the server.
  • Every enrollment, lesson completion, quiz attempt and retention update that is queued sits on the learner's computer first, in the lms_progress_outbox table, under its own id and pinned to one account and one workspace. Enrolling twice or double-clicking "complete" stores one update, because those ids are fixed (enrol:<course>, complete:<course>:<lesson>); a quiz attempt carries its own attempt id.
  • The queue is sent to the server's progress operation (lms-progress-apply) after each newly queued update and whenever the panel asks (flushProgressOutbox, POST /lms/progress/flush). An update leaves the queue only when the server reports it applied, already applied, or refused for good; anything else keeps it for the next try, so a dropped connection or an offline day loses nothing and a resend is never counted twice.
  • The server decides; the computer only proposes. lms-progress-apply checks that the learner is a live full member of the workspace, writes the enrollment as the signed-in account, grades each quiz against the answer keys of the exact lesson version the learner took (never a version not yet published), lets a must-pass quiz gate its lesson, and marks the course complete when every lesson of its current version is done. Every update counts once by its id and nothing moves backwards: a best score, a pass, a finished lesson and a finished course all stay. A malformed update is refused on its own, and a course the server could not reach is left unanswered so it is sent again next time.
  • A server that does not offer the operation loses nothing. An older relay answers "unknown operation", the flush reports not-available, and every update stays queued.
  • A suspended account keeps its queue. The relay refuses a suspended account before any operation runs, and never with not-a-member, so its updates wait instead of being dropped.
  • Two things drop updates, both with an inbox notice. An update older than 14 days, and every queued update for a workspace when the server says the learner is no longer a member. Neither is retried.
  • The queue leaves with the account. Signing out empties it, and a different account signing in on the same computer removes the previous account's updates.
  • Managers read the synced rows (getTeamProgress, GET /lms/course/:id/team-progress): a workspace admin gets every learner on the course, a manager gets the learners on their team, and a learner gets their own row. Offline, the answer is empty and marked offline rather than an error; a course with more than 500 learners comes back marked truncated. The personal workspace has no team rows.

Team dashboard

The Team dashboard (src/plugins/lms/web/src/components/LmsHrManagerDashboard.tsx in a team workspace, with its views under components/manager/) is where a manager sees each person on their team. It is the plugin's default screen, so it asks whoAmI again on every open (components/manager/use-lms-whoami.ts) rather than keeping the plugin's session-long identity. That answer is the last roles Courses knew, never a wait on the cloud (see Roles answer at once), so the one open right after a role change can still show the old roles; the next open shows the new ones.

  • One read feeds the whole Team surface. getTeamProgress answers a single course when it is given a course id, and the whole team — every learner's synced progress across the workspace's published courses, the roster with display names, and each course's lesson count — when it is not (GET /lms/course/:id/team-progress is the per-course form the command line exposes). The manager's per-course view reads the same payload instead of asking again, so opening a course never fans out into a read per course.
  • Who is on the team comes from the live role grant, not from the enrollment. A manager's team is the live members whose lmsRoles grant lists them as a manager; a row is shown only when its owner is on that team, so a learner an administrator moved to another manager disappears at once even while their enrollment still carries the old manager. A workspace admin sees every live full member. Guests are never included.
  • A team member who has not started still appears in the team filter; the dashboard distinguishes "no one on your team yet" from "nothing has started yet".
  • Completion is counted by lesson id against the published course, never by a bare count: a completion recorded for a lesson the builder later removed is not counted, and cannot turn a row into a false "complete". Percent, projected finish and the behind/on-track/complete status use the same pure rules as the local dashboard (lms-manager-aggregation.ts).
  • The read is bounded and says so. It pages up to four pages of 500 rows; a bigger team comes back marked truncated and the screen prints a line above the totals, so a cut-off table is never read as the whole team.
  • Offline is its own state. When the enrollment read reports offline, nothing else is read and the screen says it cannot reach the team right now — never an empty team. A refusal that is not offline is shown as a real error with a Retry.
  • Everyone else sees their own screen. In a team workspace a learner gets a calm "this view is for team managers" panel with a link to My learning, and no call is made; the personal workspace keeps the local rollup exactly as before.
  • The Wave 1 nudge now reaches the learner. The per-course team view has no row selection and no Nudge button yet, so a manager still nudges from the team table; that nudge used to file an alert on the manager's own computer, and it now sends the learner a notice in their own inbox instead — one per person per day — and records the reminder so the escalation clock starts from it. Reminders, the learner's own card and the manager escalation are built (below).
  • A manager has a team once an administrator assigns one. The Roles screen's managers control calls setMemberManagers, which restamps every one of that learner's enrollments and assignments; until it is used the dashboard honestly shows the empty team state.
  • One learner is one id on a computer. Signed out, Courses records progress under the placeholder local-user. When someone signs in, those rows move to their account id before Courses starts answering with it — and a course enrolled under both ids becomes one enrollment holding every completion and quiz attempt. Running the move again changes nothing, and a certificate is never deleted by it. In a team workspace Courses answers as the signed-in account from the first call; a row the move has not reached yet is refused rather than shown, and "my courses" lists under the same id.
  • Deleting an account erases everything it wrote in Courses. Account erasure removes that account's own enrolments, assignments and notices in every workspace, deletes its role grant there and takes it off every team it managed — including a team it managed in a workspace it has since left. What other people still need keeps working: a course the person owned stays published for the team with its owner shown as erased, ready for a Courses admin to take over, and its revisions, concepts, glossary terms and settings are kept the same way. A purge that cannot finish is run again by the daily reconciler.

Notices to one member

A manager or a Courses admin can send one member of the team workspace a short notice ("a course was assigned to you" or "a reminder about your course"). It reaches that person as an inbox card on their own computer. Reminders (A10) and assignments (A7) build on this.

  • Sending (notifyMember, POST /lms/notice): a manager may notice only people on their own team, an admin anyone in the workspace. The sender is always the signed-in account, never a name the screen sends. One notice per kind, course, sender, person and day: a second send that day answers alreadySent instead of a second card. The note is plain text, at most 500 characters. Nothing is sent from the personal workspace or while signed out.
  • Picking up: the person's app checks for new notices on the Shares poller's minute tick, only while Courses is installed, someone is signed in, the active workspace is a team workspace and the person is a live member of it. It reads only notices addressed to them that are not delivered yet, at most 50 at a time. When there is nothing new it slows down to one check every five minutes (with a little random spread), and speeds back up the moment a notice arrives.
  • One card per notice: each notice raises one inbox card naming the course and carrying the note, then is marked delivered. A card that could not be written, or that the inbox held back (a muted card type, the first-day hold), leaves the notice undelivered; the app tries it again after an hour, so a notice is never marked delivered without a card.
  • Read: when the person puts the card away themselves, the notice is marked read in the cloud. An inbox rule or the app clearing it for its own reasons does not count. A notice already marked read never raises a card again.
  • Limits (v1): a notice for a workspace that is not the active one waits until the person switches to it. A person signed in on two computers may see the card on both, once each. Signing out stops any check in progress, so the next account never sees the previous account's notices. Notices are kept 90 days and then removed by the cloud (the lmsNotices TTL policy on expireAt, an operator deploy step).
  • Email is not part of a notice. A notice is an in-app card; the reminder run is what sends email, on its own road above.

Missed questions

The course detail screen carries three tabs — Progress (the team table above), Missed questions and Memory — and the second one answers "what are people getting wrong?". It is the next thing a manager needs after "who is behind".

  • One read. getQuizMisses({ courseId }) (GET /lms/course/:id/quiz-misses on the command line) answers the whole tab: every quiz in the course, most-missed question first. The panel side lives in src/plugins/lms/web/src/components/manager/quiz-misses/; the rules live in src/main/services/lms/analytics/quiz-misses.ts.
  • It rides the data that is already synced. Each learner's enrollment already carries, per quiz, how many attempts they made and how many times they got each question wrong (the server counts it when it grades). The view adds nothing to the cloud and writes nothing: it sums those counts across the learners in scope.
  • A miss rate is misses ÷ attempts, rounded to a whole percent. The attempts are the quiz's own lifetime count, which the server keeps across publishes: a question added in a later version of the quiz therefore shares its attempts with versions that never asked it, so its rate reads low until that version has been taken. The raw wrong-answer count sits beside the rate, so a newly added question is still legible at a glance. A quiz nobody has taken still appears, saying so; its questions sit at 0%.
  • The server keeps the 100 most recent misses of a quiz, not every question ever missed. A quiz can hold 1,000 questions, and an unbounded miss record would eventually push a learner's enrollment document past the cloud's size limit and stop their progress being graded. Past 100 distinct missed questions the oldest are dropped (the newest are kept), the record marks itself trimmed, and every question still appears in the tab — the trimmed ones at 0% rather than not at all.
  • The manager sees the question, the rate, how many wrong answers, how many people, and who. Names come from the same roster the Team dashboard uses. Nothing else from the quiz's answer data is shown or sent — no chosen answer, no correct answer, no per-attempt breakdown. The screen cannot leak what it was never given.
  • Question text comes from the published course, not from the answer keys. Each lesson's learner revision is read (it carries the prompts and choices but never the correct answer); the builder-only keys_* revisions are never opened. A published revision never changes, so those reads are cached in memory, keyed workspace + course + revision: reopening the tab shows the payload already held in main straight away and re-reads only the enrollments and the course, never the lesson documents, and a republish is a fresh read by construction.
  • Both tabs read one payload each, and neither fans out. Opening a course is one read for the Progress tab and one for Missed questions — never a read per learner. The Progress tab keeps A12's table exactly as it was, including the absence of a Nudge button on each row: the Wave 1 nudge now reaches the learner as a notice, so the table has nothing to promise.
  • A question the builder has since replaced keeps its misses. Miss counts are recorded against the question ids people actually answered, so a question that is no longer in the course is still listed, marked "a question from an earlier version of this quiz" — and so is a whole quiz that has gone. Real data is never dropped to make the screen tidy.
  • Who may read it, three times over. The bridge's own role table needs manager, the service asserts it again before reading anything, and the audience is worked out in main from the signed-in person — an admin sees every live member, a manager only the learners whose live role grant names them. A learner, a guest, or another manager's team can never appear, even if an old enrollment still carries this manager's stamp.
  • Every state is a real one: loading, offline (its own message, never an empty course), a failure with Retry, a course that is no longer shared, a course with no quizzes, and a read marked incomplete when a lesson could not be fetched.
  • Resetting a learner's tries lives here. Each current quiz card lists who has taken it, with their tries since the last reset, and a Reset tries button that asks first ("Ana Ruiz gets a fresh set of tries on this quiz…"), calls resetQuizAttempts for the team course, and re-reads the tab. The server decides who may: an administrator, a course builder, or that learner's own manager; anyone else sees the plain refusal under the button. A reset never lowers the lifetime attempts the miss rates divide by.

Lasting memory

The third tab answers the owner's real question — "will they still know this in three months?" — and the learner sees the same measure for themselves.

  • The measure is a projection of the learner's own reviews. For each card of the course sitting in that learner's deck that has been studied at least once, the app runs the Flashcards engine's own forgetting curve (projectRetrievabilityAtDate) at three months after the learner finished the course. The figure is the mean across those cards. It is a forecast of what happens if they stop reviewing — the card's own scheduler is what keeps it up — so it reads as a floor, not a promise.
  • The horizon never sits in the past. A learner who finished more than three months ago is measured at today instead, because projecting at a date earlier than a card's last review makes the curve return 100% for every card reviewed since.
  • Only the learner's own cards are read. The card list comes from that learner's own deck pack; when no pack record exists yet it falls back to the cards actually delivered to that account, so a second account signed in on the same computer can never project the first account's cards.
  • Cards that cannot be projected are left out, never zeroed. A card never studied has no curve; a scheduling blob that will not project is skipped. If nothing is projectable the learner is told so, and nothing is uploaded, so a thin snapshot can never overwrite a measured one.
  • The learner's computer sends its own snapshot. {at, recall, cards} goes up the ordinary progress queue under retention:<course>:<hour>, to the course's own team whichever workspace is open (a course with no team sends none) — refreshed after a lesson completes and when the learner opens their own view, at most once an hour per course. A failure to compute, queue or send it is logged and never reaches the completion, the quiz or the certificate.
  • The manager reads each learner's stored snapshot and nothing else. getCourseRetention({ courseId }) (GET /lms/course/:id/retention) answers the tab: each enrolled learner on the manager's team with their figure, how many cards it is based on, when it was measured, and whether the cloud says they finished. The audience is the same one the Team dashboard uses, decided in main from the signed-in person and their live grant — a manager sees only their own team, an admin every live full member, a learner only themselves. Cards in one learner's deck on one computer are never readable by anyone else.
  • The course figure is card-weighted and needs coverage. It is the mean of the learners' figures weighted by their cards, compared to the 90% target and flagged below it — but only once at least half the enrolled learners and ten cards have reported. Below that the tab says "Not enough data yet" instead of turning a bar green on one studied card.
  • The Team dashboard carries the same figure on every course card. getTeamProgress already reads the team's enrollment rows, and each row carries the learner's uploaded snapshot, so the dashboard rolls them into its per-course figure there and then — the card adds no read and the screen never fans out one read per course (the rule the Missed questions tab follows). Each card shows the projected 3-month recall, how many learners and cards it stands on, and the same flag against the same target; below coverage it says "Not enough data yet" and what it is waiting for, so a course with one studied card can never read as a course that is failing. The rollup is the one function both surfaces use (courseRecallOf in src/shared/lms/course-retention.ts), and the verdict and the coverage floor are the one pair the Memory tab uses (retention-view.ts).
  • A course nobody on the team has started still has a card. It carries an empty figure — no learners, no cards, no percentage — and reads "Not enough data yet" rather than disappearing, so a manager can tell "no data" from "no course".
  • The same read serves the learner, on request. The learner's own card asks for self: true, which main honours whatever the person's roles are, so a manager or admin taking a course still sees their own numbers rather than the team payload.
  • Every state is a real one: loading, offline (its own message, never an empty team), a failure with Retry, a stale read with Retry, a truncated read, a learner who has reported nothing yet, and a team that has not started.
  • What it cannot say today. Its figure is only as fresh as the learner's last upload, and a learner with nothing projectable yet reports nothing.

Workspace courses and self-enrolment

The Workspace courses screen (web/src/components/catalog/LmsCatalogScreen.tsx, reached from the rail as "Workspace courses") is where a learner finds what their team shares. It is a filterable card grid; each card shows the title and how many lessons the course has, and carries one button — Enroll, or Start course once the person is enrolled.

  • The list reads every page the workspace holds. listWorkspaceCourses walks the published courses by offset, up to WORKSPACE_COURSE_MAX_PAGES (50 pages of 100). It reports hasMore only when it stopped because of that cap, so a team with more than a hundred shared courses is not silently cut off at the first page.
  • Enrolling is done for the person main resolved, and nobody else. enrollInWorkspaceCourse (src/main/services/lms/learner/workspace-enroll.ts) takes a course id and nothing else: the learner is the principal main already worked out, so a panel cannot enroll somebody else, and a forged learner id in the arguments is ignored. It needs a team workspace — the personal workspace is refused before anything is read or written.
  • The course is copied onto the learner's own computer, keeping the workspace's ids. The screen cannot invent an enrolment for a course this machine does not hold, so enrolling pulls the published course (A5's pull) and writes its rows locally in one transaction (learner/team-copy.ts), so a copy is never left half-written. The workspace's course, module and lesson ids are kept exactly, because a finished lesson is named back to the server by that id.
  • A builder whose copy is behind gets the newer version on request. If you publish a team course from a copy that someone else has moved on since (another computer, a colleague), Courses refuses the publish and offers Get the newer version. It brings the published version onto this computer, answers and pictures or files included, and keeps your current copy as a separate course named "(your earlier copy, date)" so nothing you wrote is lost; then publish again. A copy that is already current is never replaced.
  • A learner's copy follows the team; your own course is never rewritten. A course on this computer is a learner's copy when it belongs to the open team workspace and someone else owns it; a course you own here (your draft, or a course you published) is never touched. When the builder publishes a newer version, the copy catches up on its own: a check on the Shares poll (at most once every 15 minutes, at most 5 courses a pass, only while Courses is installed and you are signed in to a team workspace) reads the published version of each course you are enrolled in and pulls only the ones that moved. Enrolling again does the same at once. Copies made before lessons carried their version are brought up to date the first time.
  • Your progress survives an update. Finished lessons stay finished, every quiz attempt stays on record, and flashcards already in your deck stay as they were. A lesson the builder changed shows its new content and keeps everything you did in it. A lesson the builder removed leaves your outline, your progress figure and your certificate count, but nothing of it is deleted: it moves, with your completion, quiz attempts and cards, into the course's hidden archive, and it comes back with all of it if the builder publishes it again. Cards the builder removed stop being offered; cards they edited are updated.
  • Removed from the team? Its courses leave your computer, your history stays with the team. Within about 15 minutes of an admin removing you (or making you a guest), Courses checks, twice in a row, that the team really no longer lets you in. Then it takes that team's courses off this computer — lesson pages, their files and the flashcards behind them — drops the progress updates the team server refuses because you left, and puts one card in your inbox saying what went. It does this for every team you have courses from, not only the one that is open. Your finished lessons, quiz attempts, certificates and the flashcards already in your own deck stay, and courses you wrote are never touched. In that team every Courses screen says the team's courses are no longer yours. Your record stays on the team server for your admin and manager; if you are added back, enrolling again brings the course back.
  • Every enrolment queues exactly one update, and a retry adds nothing. The update's id is fixed (enrol:<courseId>) and the row is written with INSERT OR IGNORE, so enrolling twice — or double-clicking — leaves one local enrolment and one queued enrol update, carrying the workspace's course version. The queue is sent straight after, and the rest of its behaviour is the section above.
  • A learner who is already enrolled gets their enrollment back. Enrolling again returns the row on record rather than minting a second one.

Assigning a course with a due date

A manager or an admin can say "do this course by this date". The learner sees that promise on My learning, above their enrolled courses, and the manager sees who owes what on the course's Team screen. Reminders and the team dashboard build on these records.

  • Who can assign. A manager assigns the people their administrator put on their team; an admin assigns anyone who is a live member of the workspace, but never a guest. Assigning needs a team workspace — the personal workspace keeps everything on one computer and is told so plainly.
  • Only a published workspace course can be assigned. A draft the team cannot open yet is refused rather than promised.
  • One assignment per person per course. Assigning the same person the same course twice is safe — a retried batch, a double click or two managers arriving at once leave exactly one record and keep the due date it already had. To move the date, change it in the course's Assignments list.
  • A due date is a day, and it reads as that day everywhere. The chosen date is stored at midday UTC, so a learner anywhere within twelve hours of UTC sees the same calendar day; whether an assignment is overdue is decided by comparing calendar days in the learner's own machine's time zone, not by comparing instants, so it never reads a day early or turns overdue while the day is still running.
  • Only the assigner or an admin settles an assignment. They can move the due date or remove it; the learner, their teammates and other managers cannot. Removing it stops it showing on My learning and keeps whatever progress the learner already made.
  • What the learner sees. "Assigned to you" lists each course with its due date and a status — overdue by N days, due today, due tomorrow, or due in N days. Start course opens the course, enrolling through the ordinary workspace-course flow the first time. The status is worked out in the app's main process from its own clock, so two computers showing the same assignment agree about which day it is.
  • Code. src/main/services/lms/assignments/ holds the rules (guards, create, list, mutate) over A2's cloud store; the panel side lives in src/plugins/lms/web/src/components/assignments/.

Reminders and manager escalation

When a course has been assigned with a due date, Courses reminds the learner itself — first to them, and only to their manager if they stay behind.

  • When a reminder goes out. From the due day onwards, for as long as the course is unfinished. A course nobody assigned is never reminded (there is no date to fall behind), and a learner who has finished is never reminded. The check runs once a day, on the due date's own calendar day as this computer sees it, and the same learner is reminded at most once a day no matter how many computers they use.
  • Who delivers it. The learner's own computer raises an inbox card ("Reminder: …") naming the course and saying when it was due. If the learner's computer is not running that day — or a reminder could not be delivered — a manager's computer covers that day instead, sending the same reminder through the ordinary team-notice road, so the learner still hears about it the next time their app runs. A day the learner's own computer already recorded is left alone.
  • The manager hears last. A manager whose role names them as that learner's manager is told only when a reminder was actually delivered and the learner is still behind after the workspace's grace period (three days unless an admin changes it). That card names the learner and the course. It is sent once, and never before a reminder has gone out.
  • Tested on a moved clock. The team-cloud test bench can set the day Courses believes it is, so the due-day, overdue and grace-period journeys run without waiting for real days. Only an unpackaged test build honours it; a real install always uses the computer's own clock.
  • One reminder, never two. A reminder is written down in the team workspace before anything is shown, and only the computer whose write succeeded goes on to raise the card or send the notice. Two computers, or two managers, therefore cannot duplicate one reminder — and a restart never repeats one.
  • Nudging by hand. The old nudge wrote a card into the manager's own inbox. That path now reaches the learner as a notice in their own inbox instead, one per person per day, and still records the reminder so the escalation clock starts from it. The team table carries a Nudge button per learner (components/manager/TeamNudgeButton.tsx). A nudge needs a team workspace: from a single-computer workspace (where there is nobody else to tell) it says so plainly rather than pretending it was sent.
  • Email reminders. The same run also sends the reminder by email through the plugin's own email.send permission — the learner's email goes out before the learner's manager's, the manager gets one digest per run, and the workspace's reminderEmail setting (default on) switches the whole email leg off. Learner reminders leave as one schedule per course and due date with every behind learner as a reader, because the cloud holds 20 unfinished scheduled issues per plugin and one schedule per learner would refuse the 21st. The email carries the course title, the due or behind state, and a pointer back into Courses — never a quiz prompt, answer or score, and never an address in the renderer, a reply or a log. The learner's card and the manager's escalation are ordinary inbox cards, so the usual inbox controls (mute a card type, rules, snooze) apply to them.

Bringing your own documents into a course

A course builder can hand Courses their own material and get its text back, which is what the AI course builder works from. The reading happens in main with the app's existing extractors — the office reader for Word, slides and the other office formats, and the file-conversion engine for PDFs — so nothing is uploaded and no new package reads your files.

  • What it reads. PDF, Word (.doc, .docx, .docm), slides (.ppt, .pptx, .pptm), Excel, OpenDocument, RTF, EPUB, and plain text, markdown and CSV. An image, a video or a recording is not a document — audio and video get their own task.
  • Where the file comes from. In the panel, the builder picks a file with the app's own file window (documents.open) and adds it through the same chunked import every other course file uses (importMedia in parts), so a big PDF is never pushed through one bridge argument. Courses is then handed that stored file's reference and reads the saved copy locally; a path is never accepted from the panel. The command line is the other door: POST /lms/ingest takes {sources:[{kind:"path",path:…}]} and, because it reads a file on this computer, it takes the full-trust key only. A protected location — the app's own credentials, the ~/.claude tree — is refused there too.
  • Only a course builder may ask. The person is derived in main, never passed in; a learner-only caller is refused with a plain sentence, and the file is not read first.
  • Limits. The media store's own caps apply (50 MB for a PDF, 100 MB for other files), Courses refuses anything over 50 MB on the command-line path, up to 20 files per call, and 200,000 characters kept from each file (the rest is cut and the result says so). A call stops starting new files after five minutes and reports the rest as "ran out of time", so a slow import cannot outlive the caller.
  • One bad file never loses the good ones. Each file is read on its own: what could be read comes back, and each failure carries a sentence naming that file and what to try. If nothing could be read the call itself is refused rather than returning an empty success.
  • Plain words, never a raw error. An oversized file, a scanned PDF with no selectable text, an unsupported type and an unreadable file each get their own sentence; the raw reason is logged in main and never returned.
  • A link is somebody else's reader. A url source is not a document: a recording address goes to the audio and video reader and a page or YouTube address to the page reader (both under Ingesting a recording as course material), and a link that cannot be read refuses the call rather than coming back as one failed file beside the others.
  • The picker needs its Lab setting. Courses uses the app's plugin file access, which is on by default and can be turned off under Settings → Lab → "Plugin document access"; with it off the file window itself says the capability is unavailable.
  • Code and shapes. src/main/services/lms/ingest/ — documents.ts extracts and refuses, index.ts checks the role and routes each source. The bridge method is ingestMaterial({sources}), answered {sources:[{name,kind,text,truncated?}], failures:[{name,reason}]} — a document comes back with kind:"document" and says whether its text was cut, a recording or page with its own kind; the panel sends {kind:"media",sha,name} (the file the chunked import stored), the command line sends {kind:"path",path}.

The Courses list

  • A fresh list offers both ways to start. With no courses yet, the list shows New course (a blank course you fill in) and, beside it, New with AI (the AI build wizard), so someone who does not want to write every lesson by hand is one click from the builder.
  • The sample course is already there, and the button brings it back. The first time someone who may build courses opens Courses, "Giving Feedback That Helps" is added once and they are enrolled in it, so it sits on their own list and in My learning ready to start — nothing to click first. It is a short, real course on the SBI feedback method (Situation, Behavior, Impact) that uses everything Courses can do: a page lesson with text, a picture, a concept card, a glossary card and a link card; a lesson that is just one YouTube video; a page with a calm-breathing audio clip, a printable PDF worksheet, an embedded talk and a practice quiz that need not be passed; an old-style written lesson; a lesson that is just one downloadable planner; and a final quiz that must be passed at 80%. It brings two course concepts (with article, picture, video and audio versions), six glossary words, four lesson resources and 13 flashcards, one with a picture. Finishing it fills the learner's deck and earns the PDF certificate. The list's header carries Add sample course, which brings back a copy you deleted and enrolls you in it; pressing it while you already have one opens the copy you already have instead of adding a second, and opening Courses never re-adds a sample you deleted. One computer holds one sample, whichever local identity it was built under. Agents add it with POST /lms/sample-course (201 when it was added, 200 when it already existed). Only someone who may build courses gets one; for everyone else opening Courses does nothing.
  • Deleting a course is a retire, not an erase. Delete course in the course editor's settings rail asks first, then takes the course out of the builder list. Learners who already finished it keep their completions and their certificate, and the course's share link is turned off.
  • Retiring a team course takes it out of circulation. Retire from team, in the same settings rail, asks first and names the course, then stops offering it to new learners: it leaves the team's Workspace courses list, and enrolling in or pulling it is refused. Learners already enrolled keep their progress and their certificate, nothing is deleted, and the course stays on your own list so you can still edit it. Only the course's builder or a Courses administrator may retire it, and it needs a team workspace — in a personal workspace the rail says so instead of offering the button. Retiring is safe to repeat, and a course that was never published is refused with a plain sentence.

The Share button in the course editor turns a course into a public Shares page that anyone with the link can read, signed out included.

  • Who can share. The person who made the course, or a Courses administrator, while signed in to Omniscio. Anyone else is told why and nothing is published. A course with no lessons cannot be shared yet.
  • What the page shows. One tab per module, each lesson in order: its text, links, YouTube and Vimeo videos as links, and small pictures (PNG, JPEG, GIF or WebP up to 512 KB, 3 MB per page). Larger pictures, uploaded videos, PDFs, audio and files are named rather than shown. Quizzes show their questions and choices, never the answers or explanations.
  • One link per course, until you turn it off. A course link does not expire on its own. Pressing Update with latest edits republishes the same link with the current course. Turn off link takes the page down, and so does deleting the course; if it was taken down from Shares instead, the next share makes a new link.
  • Copying a course from a link. A builder chooses Copy from a link next to New course and pastes a share page's address. Courses makes a new draft they own. Because the page never carries answers, every quiz arrives needing its answers set again and learners cannot take it until then; a quiz inside a page lesson becomes its own quiz lesson right after it. Pictures and files this computer does not already hold become a short note naming what was left out. Only Omniscio share pages (https://shares.omniscio.com/s/…) are accepted.

Publishing to the public library

The Publish dialog has a second choice under the team one: Also publish to the public library. Turn it on, check the title, add a short summary and up to ten tags, and confirm — the course is listed at once, with no review step.

  • Who can publish. A course builder, signed in. In a team workspace the course must already be published to the team (the dialog does that first, then the library), and only the person who made it or a Courses administrator can list it. In your personal workspace the library is the only place to publish to.
  • What gets listed. The title, summary, tags and your display name, plus the course's share link — publishing makes or refreshes that link first, so the library and the link always show the same version. Quiz answers are never included; someone who copies the course sets them again.
  • Publishing again updates the same listing to a new version. You can publish up to 20 times a day; an attempt the library refuses does not count.
  • Withdrawing a listing takes it out of the library; only its author can.
  • Removed courses stay removed. A course taken down after a report cannot be published again, and neither can the same course content or anything from an author who is currently blocked.
  • Pictures and files in a listing are not carried into a copy yet: a copy keeps the media your computer already has and names the rest.

Browsing and copying from the library

Library on the Learn rail lists what people have published, newest first. The search box narrows it by title, summary, author or tag, and ignores accents and case, so "securite" finds "Sécurité".

  • Only what can be read is listed. A withdrawn listing, one taken down after a report, and one whose share has been suspended, revoked or expired never appears; opening one anyway answers "That course is not in the library."
  • A listing opens to a preview. The course's title, author, summary, tags and the outline of its modules and lessons are shown before anyone decides to copy.
  • Copy to my courses makes your own editable copy: the course, its modules and its lessons. Quiz answers are never included, so every quiz arrives needing its answers set and learners cannot take it until then; a quiz inside a page lesson becomes its own quiz lesson right after it. Pictures and files this computer does not already hold become a short note naming what was left out, exactly as a share-link copy behaves.
  • Builders copy; everyone reads. A learner can browse, search and preview; the copy control is off and says only a course builder can copy a library course. Main refuses the copy for anyone else, whatever the panel shows.
  • Your copy is a local draft owned by you, and it records which listing it came from.

Reporting a library course, and taking one down

A reader who finds something wrong in the library reports it, and a super-admin can take a reported course down.

  • Reporting (reportLibraryListing, the relay op lms-library-report): any signed-in learner may report a listed course by picking a reason. The screen sends only the listing and the reason — Courses never asks who wrote the course or which page to report. The server reads that listing's own bound Share itself, so a report can only ever point at the course it names.
  • One report path, not two. The report goes into Omniscio's ordinary Shares report flow: the same report row, the same count against the course's page and the same note to its author. A course reported from Courses and one reported from its Shares page cannot be counted twice as different things.
  • One account is one source. The reporter is counted by a salted account scope rather than their email address, so the same person signed in another way is still one report.
  • Nothing is probeable. A course that is missing, withdrawn, taken down, or whose Share is no longer served all answer the same "that course is no longer in the library", so a report cannot be used to find out which of those is true. A reason outside the fixed list is refused and never stored.
  • Taking down a reported course (a super-admin act on its Share) marks the listing taken down and, in the same transaction, blocks the course's own content by its fingerprint and blocks its author by account. The listing drops out of the library and stops being copyable in that same moment, and republishing the same course — or publishing anything from that author while the block stands — is refused. Publishing already refused a blocked course or author; a takedown is what puts them there.
  • Restore clears only its own block. Restoring the Share clears the taken-down mark and removes just the listing that takedown blocked; a block doc is deleted only when its list empties, so two takedowns against one author or one course need two restores. Both changes are written before the Share itself, so a failure leaves nothing half done and a retry behaves like a first attempt.
  • On the screen: each listed card on the Library screen carries Report, which opens LmsReportDialog and sends only the listing and the reason.

The lesson page editor

A lesson saved as a page (an ordered list of blocks) opens in a block editor instead of the older markdown box. An older document lesson opens in the block editor too, unless its content is something the block editor cannot keep — it then stays in the older markdown editor where it remains fully editable. An older quiz lesson opens as a page holding one quiz block, so the builder gets the pass-mark and "Must pass to finish this lesson" controls on content imported before pages existed; a quiz one block cannot hold keeps the older quiz editor. Nothing stored is rewritten until the builder saves. The Add-lesson menu does not create page lessons yet.

  • Preview is a button as well as a key. The page-lesson editor's header carries Preview beside Save. It shows the preview key as a key cap (Ctrl+Alt+Enter by default; a rebind changes the cap, and an unbound key shows none) and opens the same learner preview sheet the key opens, from the same draft — one function serves both. Save stays the header's one accent-filled button.
  • Text blocks are written in place. Each text block is its own editor with headings, lists, quotes, code and links, saved as markdown. A block you never touched is saved back exactly as it was, byte for byte.
  • A document lesson's body is written in that same editor. The older document lesson keeps its own screen, but its body is now written in the same rich markdown editor a text block uses, so a # heading line is a heading while the builder types instead of raw text in a box, with the learner's preview beside it. A body the editor cannot keep (a table, a checklist, a picture) opens in the markdown box instead — still fully editable and saved exactly as it is. Nothing stored changes shape: a document lesson still saves its markdown body. Code: useMarkdownRichEditor is the one editor setup, used by TextBlockEditor and by LmsLessonEditorDoc.
  • Text the editor cannot keep opens read-only. If a text block holds a table, a picture, a checklist or HTML the editor would drop, it shows as a read-only card with its markdown, is saved unchanged, and can still be moved or deleted.
  • Video blocks play in the lesson. Paste a YouTube, Vimeo or Loom address into a video block and the learner watches it right there (YouTube plays on its privacy-enhanced host), with an optional caption and a "Watch on YouTube", "Watch on Vimeo" or "Watch on Loom" link in case the player cannot load. A video added by a newer version of Courses, for a player this version does not know yet, shows as a link card and is kept unchanged. When the player itself cannot load (no network, or the provider is blocked), the lesson stays put and the block adds a plain link card to the same video beneath the player, so the video is always one click away — and a failed player never closes the lesson or the Courses panel. A plain https address becomes a link card the learner opens in a new tab — never a player — and anything that is not an address Courses can use (a typo, an http:// link, a look-alike site) is refused in plain words instead of being saved. A video uploaded into the lesson itself says it plays in a later update.
  • Quiz blocks are edited in place. Questions, answers, the correct answer, explanations, the pass mark and the "Must pass to finish this lesson" switch are all on the block. A blank question or answer stops the save with a message naming the question.
  • Link cards point the learner at a web page. Paste a web address into a link block and the learner sees a card with the title, the site and an optional description, which opens the page in their browser; leave the title blank and the card shows the site name instead. A YouTube or Vimeo address plays in the lesson rather than becoming a card. Only an address Courses can open is accepted — a typo, an http:// link, a javascript: link or a look-alike site is refused in plain words — and a link block with no usable address is left out of the save rather than stored half-finished.
  • PDF blocks are edited where they sit. Choose a PDF (up to 50 MB) and it is stored in the course media store by its fingerprint, so the lesson itself never carries the file's bytes; an optional title names it above the reader. The builder sees the learner's own reader on the block as soon as the file is chosen. A PDF that the app cannot carry in one upload is refused in plain words, and a block with no PDF yet is left out of the save rather than stored half-finished.
  • Pictures sit inside the lesson. An image block holds a picture you choose or drop into it, a description and an optional caption. The picture is copied into Courses' own media store, so the lesson keeps working if the original file moves or is deleted, and the description is what a learner who cannot see the picture reads — so a picture with no description stops the save, with the message on the block itself. Choosing a file and dropping one onto the block both work, PNG, JPEG, GIF and WebP are taken, and anything else — a PDF, an oversized picture, an empty file — is refused in plain words before anything is uploaded. A picture over 10 MB is refused here, before anything is uploaded. A block you added and never gave a picture to is not saved with the lesson, so reloading shows the lesson without it.
  • Audio blocks carry a recording you upload. Choose an MP3, M4A, WAV or OGG file, add an optional title and an optional transcript, and the learner gets a plain player that streams from Courses' own media route — so they can pause and scrub anywhere in it without waiting for the whole file, and the file is never copied into the lesson. The recording can be replaced on the block; removing it means deleting the block. A file over 100 MB is refused on the spot with a sentence naming that limit, and a file that is not audio is refused naming the kinds it takes. The player appears once the lesson has saved, because Courses only hands out a file to the lesson that now refers to it.
  • Files travel with the lesson, for download. A file block hands the learner a worksheet, a template or a checklist. Choose the file once and it is copied into Courses' own media store, so the lesson keeps working if the original file moves or is deleted. The learner sees a card with the label you wrote (or the file name when you left it blank), the file name, its size and a type icon, and Download saves the exact file back to their computer. A picture, PDF, audio or video file, or a Word, Excel, PowerPoint, text, CSV or zip file is taken; anything else, an empty file, or one over 100 MB (50 MB for a PDF) is refused in plain words before anything is uploaded. Nothing about the file is stored on the page itself — only its reference — so the lesson stays small. A block you added and never gave a file to is not saved with the lesson, so reloading shows the lesson without it.
  • PDF blocks hold a document you upload. Choose a PDF, add an optional title, and the learner reads it inside the lesson, page by page. The file is copied into Courses' own media store by its fingerprint, so the lesson itself never carries its bytes, and the builder sees the learner's own reader on the block as soon as the file is chosen. A file that is not a PDF, an empty file, or one over 50 MB is refused in plain words before anything is uploaded. The app can really carry about 2.4 MB in one upload today, so a PDF that trips that on its way through gets the same plain sentence instead of a raw error; chunked upload lifts both limits. A block you added and never gave a PDF to is not saved with the lesson, so reloading shows the lesson without it.
  • The remaining block kinds wait for their own editors. They show a card you can move or delete, and a block from a newer version of Omniscio says so. Both are saved unchanged.
  • Adding and arranging. Type / at the start of a word to open the block menu (arrow keys and Enter pick, Escape closes; a / typed again opens it again). A new block takes the text cursor at once. Reorder by dragging the handle, with the up and down buttons, or with Alt+Shift+↑ / ↓ inside the block (the title and minutes fields move nothing). Deleting a block that has content asks first.
  • Saving. The editor saves 1.5 seconds after you stop, Ctrl+S saves at once, and Back saves before it leaves. The header says Saved, Unsaved changes, Saving…, Couldn't save or Can't save. Back waits for a save already running before it decides; only when the latest changes really could not be saved does it ask before leaving without them.
  • Size limits. A lesson over 800 KB, over 200 blocks, or with a text block over 200,000 characters is refused with a message naming the limit it hit — nothing is cut short. The same check runs where the lesson is stored (createLesson and updateLesson refuse it with LESSON_TOO_LARGE), so a save from the command line or another tool is refused the same way. Older document and quiz lessons are not held to it when they are saved, so the Docebo importer is unaffected; a stored quiz bigger than one page is covered under Quizzes below.
  • The "AI tutor" lesson type is gone from the Add-lesson menu. It was a placeholder; the AI helper covers the need. Existing AI-tutor lessons still open.

Selecting text in a lesson

Select text in a lesson and right-click it — in My learning and in the builder's Preview — and a menu opens to act on that text. Shift+F10 and the Menu key open the same menu for the selection, because that is the platform's own context-menu key; both are refused as structural in Courses' shortcut settings (LMS_STRUCTURAL_COMBOS), so no command can take them.

  • Copy puts the whole selected text on the clipboard and says so; if the clipboard refuses, it says that instead of pretending.
  • Look up in glossary opens the term when the selection is a glossary term, and the course's Glossary screen when it is not. The builder preview loads the lesson's glossary too, so its terms open in place and its marks show as a learner would see them; when the selection is not a term the preview closes and the Glossary screen opens.
  • Ask the course helper about this opens the helper with the selection attached, answered from the lesson you are reading. It is left out of the menu where the helper has no lesson to answer from — a preview opened from the course outline rather than from a lesson editor.
  • Make a flashcard from this appears to someone who can build courses and to every learner reading a lesson. It prefills the front with the selection and asks for the back. In a builder's preview the card joins this lesson's deck — the same deck that joins the learner's flashcards when the lesson is finished. On a lesson a learner is reading, the card is private to that learner: it is saved to their own flashcards at once, in the course's pack, and the dialog lists the cards they have already made from that lesson so they can edit or delete them — an edit or a delete follows into their deck, and if they removed the course deck the card waits and comes back with it on Restore. A card someone made is never shown to another learner, is never course content, and never touches the course's retention figures. A front longer than a card face, an empty back, or a failed write is refused in plain words rather than truncated or half-saved.
  • No notes or highlights. A "add a note/highlight" action needs a back end Courses does not have yet — there is no note store, route or screen — so it is deliberately not in this menu.

The menu opens only when the selection is inside the lesson body; a right-click with nothing selected opens nothing. Actions read the text captured when the menu opened, so clicking a row after the page selection has collapsed still acts on what you selected.

Asking Courses to rewrite a block

A course builder can point at one block of a lesson and ask Courses to redo it — "Make this simpler", "Add an example", "Turn into a quiz", or any sentence of their own. Courses reads that block and the text of the blocks around it, writes a replacement, and hands it back.

  • A text or quiz block, and only those. Asking to rewrite a picture, a video, a PDF, a file, a link card, a glossary or concept reference, or a block made by a newer version of Omniscio is refused in plain words — the app has nothing it could write back in that block's place, and a rewrite never silently drops a picture or a file.
  • The neighbouring blocks are read as context, never rewritten. Only the text of the blocks around the selected one is sent, so a rewrite of one paragraph still fits the lesson it sits in. A picture, a file or a quiz next to it is never sent.
  • You get a proposal, not a change. Nothing on the lesson is written: the answer is one or more new blocks the builder places, edits or rejects. A rewrite that asks for questions comes back as an ordinary quiz block — default pass mark 80%, "Must pass to finish this lesson" on — so it is graded by the same rules as any quiz.
  • It writes words, never files. Courses answers with written material or a quiz, never an image, a recording, a PDF or a link card it cannot really produce.
  • A block over 20,000 characters is refused rather than half-rewritten, with advice to split it into smaller blocks first. A long block is never truncated and replaced with a shorter version of itself.
  • Builders only. A learner is refused with the same sentence every builder-only action gives.
  • It costs AI spend under the same daily cap as the outline generator, and answers a "not configured" sentence without calling anything when no Anthropic key is connected in Settings. A model or network failure answers one plain sentence and never leaves the builder with a broken screen; a reply that is not a usable block is asked for up to three times before it does. Every attempt is billed to lms:block-rewrite, so the Courses daily cap counts it.
  • The panel calls it when the editor's rewrite menu arrives. Until then it answers on the Courses command line as POST /lms/lesson/:id/block/:blockId/rewrite with {"instruction":"Make this simpler"}, which takes the full-trust key: the answer is {"proposal":{"lesson_id":"…","block_id":"…","blocks":[…]}, "degradedReason":null, "elapsedMs":…, "model":"…"}, and a rewrite nothing usable came back for answers proposal: null with the sentence to show.

Quizzes

A quiz is a block on a lesson page. The app grades every attempt itself, so what the learner's screen sends can never pass a quiz on its own.

  • Builders add one from the block menu (type /quiz). Each quiz has an optional title, a pass mark (0–100%), and one to a thousand questions with two to a hundred answers each, one marked correct, and an optional explanation (a question, an answer or an explanation may run to 20,000 characters). A new quiz starts with one filled-in question, so the page keeps saving while it is being written.
  • "Must pass to finish this lesson" is the builder's switch on each quiz, on by default. On: a failed attempt never finishes the lesson, and the learner can try again. Off: taking the quiz once is enough, pass or fail. A page with several quizzes finishes only when each one meets its own rule.
  • Learners answer every question, then Submit answers. The result shows the score, pass or not, and which questions were wrong. The correct answers and explanations appear only after a pass, or straight away on a quiz that is not must-pass. Try again clears the answers. The Complete and Continue button opens the moment the rule is met.
  • Every attempt is kept with the pass mark it was graded against, so editing a quiz later never changes a past pass or fail. A finished lesson stays finished.
  • Fifty tries per quiz, then a reset. Past fifty, the learner is told to ask their course builder to reset their attempts. A reset gives the learner fifty fresh tries on that one quiz and deletes nothing: every past attempt, score and pass stays in the history, a passed quiz stays passed, and an optional quiz already taken stays satisfied. The reset is a marker — the number of tries made so far — and only tries after the latest marker count toward the fifty. resetQuizAttempts is the one entry point (POST /lms/quiz/reset on the command line):
    • A course kept on this computer ({ scope: 'local', enrollmentId, lessonId, blockId }): a course builder or an administrator. The marker is a row in lms_quiz_attempt_resets. In the personal workspace, where you are your own course builder, a quiz whose tries are used up shows a Reset my tries button under the "used every try" line; it resets that quiz and offers the retake at once.
    • A team course ({ scope: 'team', courseId, learnerUid, blockId }): the team's server is the only judge of the cap, so the reset is the lms-quiz-reset relay op. It lets a live administrator, a live course builder, or the learner's own manager (assigned by an administrator, for the learner's current membership) reset, and sets exactly one field on the learner's team record, quizzes.<quiz>.attemptsAtReset. The lifetime attempts count is untouched, so the Missed questions rates stay true. The learner's computer reads its tries left from the server; its own attempt rows are history only. The manager's control is on the Missed questions tab (below).
    • Refusals are plain words: a learner, a manager who does not manage that person, someone signed out, a learner who has left the workspace, and a quiz never taken are each refused with one sentence.
  • Older quiz lessons follow the same rules. A quiz lesson made before pages existed counts as one must-pass quiz. Learners read it as the same quiz block, and its builder opens it as a page with that block — so the switch and the pass mark apply to imported content too.
  • One limit for both sides. The older quiz storage and a quiz block read the same answer, question and text limits, so a quiz an import accepted always opens as a quiz block: an imported question with twelve answers, or with a long question, answer or explanation, is delivered and graded like any other — including the long tests a Docebo import brings (one with 150 questions submits, grades and passes like any other).
  • One quiz size: a thousand questions, everywhere. The editor, the import, the learner page and the team's grading server all accept up to 1,000 questions per quiz (CONTENT_LIMITS.questionsPerQuiz); the server's own copy (LMS_PROGRESS_LIMITS.questionsPerQuiz, in both server folders) is held equal to it by a test, and a 1,001-answer attempt is refused.
  • A quiz nobody can answer shows a notice, never a blank lesson. When a stored quiz holds more than a thousand questions, marks an answer that does not exist, or is bigger than one lesson page (800 KB), the learner sees one line saying the course builder must fix it, and the quiz cannot be submitted at all. The lesson's Complete button stays disabled with that same sentence as its reason, so the learner is never offered a finish the server would refuse. The builder still gets the older quiz editor, where the fix belongs.
  • A team course's quizzes are graded by your team, online. A course pulled from a team workspace arrives on the learner's computer without its answers, so the app cannot grade it there: Submit answers sends the attempt to the team's server, which grades it against the answers of the exact course version the learner has, and the result comes back with the score and the questions that were wrong. It needs a connection and the course's own team workspace open; without them the learner is told to check and submit again, and nothing is counted. One attempt is graded at a time: a second click while the first is still out is refused with "still being graded" and sends nothing. If the team took the attempt but its grade could not be read back, the learner is told a try was used (never to submit again), and the tries left after a graded attempt follow the team's own count. The correct answers are never shown for a team quiz, even after a pass.
  • Reader boundary. Learner course reads return an outline without lesson configs; lesson page reads pass through toLearnerPage, which omits correct_choice_index and pre-attempt explanation. The UI reveals correct answers only after the quiz rule permits it (after a pass, or after any attempt for an optional quiz).

Concepts

A concept is one idea explained once, in as many ways as a learner needs: a video, an article, a Wikipedia page, an audio clip, slides, a worked example. A lesson links to the concept instead of repeating an explanation, so the same idea stays in one place.

  • A concept belongs to the workspace or to one course. Workspace concepts are readable from every course in the workspace; a course-only concept stays inside its own course. Concepts is where a builder keeps both: choose the scope while adding one, and every concept in the list carries a chip saying which scope it is in.
  • A concept holds versions, and each version is one piece of content. Pick how the learner should see the version named — Video, Article, Wikipedia, Audio, Slides, Example or Other — and then what it holds: writing, a picture, a video, a PDF, a recording, a file or a link. The concept page draws the chosen version with the same block viewers a lesson page uses, and the switcher above it lists every version; the number keys pick a version by its place in that list, and R jumps to the concept's resources.
  • The builder decides the order. Move a version up or down and the whole list is saved in one write, so the order is never half-applied. There are at most 20 versions per concept, every version needs a title, and a version's stored content is capped like the rest of a concept document.
  • Resources hang off the concept too. The concept page mounts the same resources panel a lesson does, so a handout or a further-reading link can sit beside the versions.
  • Lessons link to concepts with a concept card. In the lesson editor's slash menu, Concept inserts a card; pick which concept it points to. The learner sees the concept's name and summary with a button that opens it, and the concept page lists every lesson that links to it under Used in — a read-time list, never a stored back-link.
  • Deleting a concept takes its versions and resources with it. A lesson that linked to it shows a plain "the concept this card pointed to was removed" note rather than an empty card.
  • Only course builders change concepts. Everyone who can read a lesson can open the concept it links to; adding, editing, deleting, and reordering versions needs the builder role, and every write is checked again in the app's main process. A workspace-wide concept in another workspace is out of reach; a course's own concepts, and the pictures and files in them, are reachable exactly when the course is.
  • Code. src/main/services/lms/concepts/ holds the rules — store.ts reads and writes lms_concepts and lms_concept_versions (the 20-version cap sits in the INSERT itself, and deleting a concept soft-deletes its versions and its resources in one transaction) and index.ts answers the nine bridge methods behind the principal and workspace checks. The screens are src/plugins/lms/web/src/components/concepts/ — the list, the concept page, the version editor and the concept card the lesson editor inserts — and the command line reaches the same methods at /lms/concepts.

The AI build wizard (a course from a topic)

A course builder types what the course should teach, who it is for and how deep it should go, and AI drafts the whole course: the modules, a reading lesson for each idea with its own flashcards, and a knowledge-check quiz in each module. Nothing is saved until the builder chooses Save course, and everything stays editable before and after.

  • Where. The sidebar's AI build wizard (Courses › New with AI). Its other half drafts from the builder's own material — see The AI build wizard (a course from your own material) below.
  • How it drafts. The existing outline step plans the modules and lessons, then each lesson is written on its own (six at a time), so one stubborn lesson never sinks the course. The whole draft is held inside three minutes, under the plugin bridge's 200-second reply ceiling: no lesson call starts once there is no longer time for it to finish. A lesson that cannot be written after two tries, or that the daily AI cap or the time budget stops, is kept with its title and an empty text block, and the wizard says how many lessons still have no text (the count follows the builder's edits).
  • What the builder can change before saving. The course title and description; each module's title; each lesson's title and text; each quiz's pass mark, Must pass to finish this lesson switch (on by default) and questions (the same quiz editor the lesson page uses); each lesson's flashcards; and the draft's glossary terms. Modules, lessons and terms can be removed. Save stays off while a title, a question, an answer or a card side is empty, or a quiz goes past the draft's limits, and says which. Ctrl+S saves (rebindable in Courses Settings, shown in the Save button's tooltip); Enter in the topic box drafts.
  • What a saved draft becomes. One ordinary course: every lesson is a page lesson (format: 'page') of text and quiz blocks that opens in the lesson page editor, every quiz carries its answer key (builder-only, as always) and the builder's must-pass choice, and every flashcard is an ordinary course-deck card, so it reaches learners through Flashcards when they finish the lesson. The save is one database transaction: if any part is refused (a lesson over the page limits, say), nothing is written.
  • Who can. Only a course builder: both calls check the builder role from the server-derived principal and refuse anyone else before any AI call or write.
  • No key, no call. With no Anthropic key connected the wizard shows "Connect an AI account first" and never calls the AI.
  • The draft arrives with its glossary. One extra call writes the course's key terms — a word or short phrase, the other names the course uses for it, and one or two plain sentences defining it — and they appear in the wizard as an editable Glossary terms section, one row per term. They are saved with the course, as the new course's own terms, so lessons mark them from day one. A word the workspace already defines is left out of the draft rather than duplicated: the workspace definition still applies to every course, so the learner is never shown two meanings for one word. If that call fails, or the daily budget runs out before it, the draft simply arrives with no terms — it never fails the course.
  • What it leaves out for now. Nothing from the builder's point of view: the wizard drafts the modules, lessons, quizzes, cards and glossary terms, and everything it drafts stays editable.
  • For agents. proposeCourseFromTopic (POST /lms/builder/propose-topic, full-trust key only) returns { proposal, degradedReason, incompleteLessons, elapsedMs, model } and never writes; applyCourseProposal (POST /lms/builder/apply) takes { proposal }, validates it again in main and answers the new course (201). The proposal shape and its limits (6 modules × 6 lessons, 200-character module and lesson titles, 20 blocks, 20 questions of 2–6 answers, 30 cards per lesson, 25 glossary terms, 8 MiB in all) are src/shared/lms/course-proposal.ts; a term is { term, aliases?, definition_markdown }, and applyCourseProposal writes it through the glossary service, so a term whose word or other name is already defined in the workspace or the course is skipped rather than saved twice — the save answers the new course as before, and a skipped term is never an error. Code: src/main/services/lms/builder/ (topic-prompt.ts the prompts, topic-generator.ts the drafting, apply-proposal.ts the save) and src/plugins/lms/web/src/components/builder/.

The AI build wizard (a course from your own material)

A course builder adds the material the course should teach — documents, recordings, web pages and YouTube links — and AI drafts the whole course from it: modules, a reading lesson for each idea with its own flashcards, and a knowledge-check quiz in each module. Nothing is saved until the builder chooses Save course, and everything stays editable before and after.

  • Where. The sidebar's AI build wizard (Courses › New with AI), with From a topic and From my material as its two halves.
  • It reads the material once. Each file is uploaded through the same chunked import every other course file uses (importMedia), then one call hands Courses the stored file's reference or the link and Courses reads it here, with the readers above — so a recording is transcribed once, never twice.
  • How it drafts. Courses plans the outline from the material, then writes each lesson with that material in front of it, so the teaching follows what the builder supplied instead of general knowledge. The rest is the topic wizard's drafting: six lessons at a time, two tries each, inside the same three-minute draft — and the glossary is written from the same material, so the terms it defines are the ones the course actually uses.
  • A file it cannot read is named. Anything that failed to read comes back beside the draft with a plain sentence naming that file, and the course is still drafted from the rest; a link that cannot be read refuses the call, exactly as the ingest sections say. If nothing could be read the call is refused with a plain reason.
  • Your material stays with the course. Each file or link added is attached to the course's first lesson as a resource, in the same save, so the source is one click away afterwards.
  • AI trouble is a sentence, never a crash. No key, the daily AI cap, an unreachable service, or an outline the shape check refuses: each comes back as a plain sentence the wizard shows, and nothing is saved.
  • No key, no call. With no Anthropic key connected the wizard shows "Connect an AI account first" and never reads or sends anything.
  • Who can. Only a course builder: the call checks the builder role from the server-derived principal and refuses anyone else before any read or AI call.
  • For agents. proposeCourseFromMaterial (POST /lms/builder/propose-material, full-trust key only) takes { sources } — the same source shapes POST /lms/ingest takes — and answers { proposal, degradedReason, incompleteLessons, elapsedMs, model, failures }, where proposal.sources carries what the draft was built from. It never writes; saving is the same applyCourseProposal the topic wizard uses. Code: src/main/services/lms/builder/ (from-material.ts the material path, course-draft.ts the lesson drafting the two halves share, topic-prompt.ts the prompts) and src/plugins/lms/web/src/components/builder/BuilderMaterialForm.tsx.

Glossary terms

A glossary is the short list of words a course teaches and the meaning each one has. A builder defines them once for a whole workspace or once for a single course, and a lesson can then recognise a word wherever it appears in the text and show its definition.

  • Every term is a word, a definition and, if you want, the other names for it. "Cell membrane", its definition, and "plasma membrane" as another name — so text that uses either name is recognised. A term can hold up to 10 other names.
  • A term belongs to the workspace or to one course. Glossary is where a builder keeps both: choose the scope while adding the term, and each term in the list carries a chip saying which scope it is in.
  • A course's own term wins. Where a course defines the same word (or the same other name) as the workspace, the learner reading that course sees the course's definition; the workspace's definition still applies everywhere else. A term never hides another course's terms.
  • One word, one definition per scope. Adding a word, or one of its other names, that is already defined in the same scope is refused with a plain sentence rather than silently overwriting what is there — edit the existing term instead. Deleting a term frees its word for a new definition.
  • Only course builders change the glossary. Everyone who can open a lesson can read the terms; adding, editing and deleting needs the builder role, and every write is checked again in the app's main process.
  • Each term stays on the machine it was written on for now. A workspace-wide term belongs to its workspace: one written in your own workspace is never listed or edited from a team workspace, and a team's workspace terms are not touched from your own. A course's own terms follow the course instead: a team course's terms only inside that team, and a course written on this computer's terms wherever its owner (or someone taking it) has Courses open, so terms written while different workspaces were open show as one list.
  • Code. src/main/services/lms/glossary/ holds the rules — store.ts reads and writes lms_glossary_terms, resolve.ts is the one resolver every reader uses (workspace terms plus the course's own, course first), and index.ts answers the five bridge methods behind the principal checks. The screen is src/plugins/lms/web/src/components/glossary/, and the command line reaches the same methods at /lms/glossary.

Glossary marks in a lesson

A learner reading a lesson sees every glossary word quietly underlined, and can ask what it means without leaving the page.

  • Every name of a term is recognised — the word itself and each of its other names — in ordinary lesson text, whatever its capitalisation. A phrase is marked only as a whole word: a term written as "cell" never lights up inside "cellar", and a name such as "C++" or "café" is matched as written.
  • Never in a heading, a code sample or a link. The marks stay out of headings, code and link text, and they are not part of the Tab order, so reading and typing carry on unchanged.
  • Click, or rest on a word, and its definition opens beside it with a chip saying whether the word comes from this course or from the workspace. Escape, a click elsewhere or the close button dismisses it, and on a phone it opens as a sheet at the bottom of the screen.
  • A course's own definition is the one shown. The lesson is handed the list main already resolved, so a word the course defines itself never shows the workspace's meaning.
  • Selecting a word offers "Define" when it is a term, which opens the same definition, and Ask the helper, which opens the AI helper with that term and its definition attached, the way a selected passage is attached. The term's own definition is the one the helper receives — never quiz text or an answer key — and a selection inside a quiz block offers Define alone, so an in-progress quiz never reaches the helper.
  • D opens "Terms on this page" — only the terms the page actually uses, in the order they appear. Filter the list, and choosing a term scrolls to its first use and shows the definition there. The list works even with the underlines switched off.
  • The underlines can be turned off in Settings, under "Mark glossary terms in lessons", for the person reading.
  • A lesson never depends on the glossary. If the terms cannot be read, the text renders exactly as before, with no marks and no error in the middle of the page.
  • Code. src/plugins/lms/web/src/components/page/glossary-marks/ holds the whole interaction: glossary-marks-model.ts is the one matcher (buildTermIndex, findTermSpans, termForPhrase), glossary-marks-markdown.ts is a rehype visitor that wraps a matched word in a span[data-glossary-term] and skips a link, code, a heading or an image whole, and GlossaryMarksProvider.tsx loads the lesson's terms, handles clicks, hover, the selection pill and the D list. The marks ride the one markdown renderer: LmsMarkdownPreview takes an optional rehypePlugins, and TextBlockView passes the visitor in, so a text block and a recording's transcript are marked by the same renderer as everything else. GlossaryTermPopover.tsx, DefineSelectionPill.tsx and TermsOnThisPage.tsx are the three surfaces.

Resources on a lesson or a concept

A lesson or a concept can carry any number of resources — links, articles, videos and files — each with its own label. They hang off the content rather than inside it, so the page itself stays short.

  • The builder adds them from the lesson editor. The editor's right rail has two tabs, Cards and Resources. Resources lists what is attached, and Add resource offers a link or article, a video, or a file. Every resource needs a label, and Save waits until the link, video or file is finished, so a half-made resource is never stored.
  • What a resource can hold. A link card (any https address Courses can open, the same rule a link block follows), a YouTube or Vimeo video, or a file from the computer — so the fields are the lesson editor's own link, video, file, PDF and picture editors. A resource may also hold a PDF, a picture or a recording that another part of Courses attached.
  • Learners see them under the lesson. A lesson that carries resources shows them below its content with no controls; a lesson with none shows nothing extra at all. The concept page mounts the same panel.
  • The builder decides the order. Move a resource up or down and the whole list is saved in one write, so two builders cannot leave the order half-applied.
  • Limits, in plain words. Up to 100 resources per lesson or concept, a label up to 300 characters, and up to 64 KB of stored detail per resource. A blank label, a kind a resource may not hold, or an item already at its limit is refused with a sentence naming the problem instead of being saved.
  • Who may see and change them. Whoever can open the lesson or concept reads its resources. Only a course builder can add, change, reorder or delete one, and an item in another workspace is out of reach. Deleting a resource stops it appearing beside the item; the file itself is only collected from the store once nothing else in Courses refers to it.

Search over Courses

  • One search covers everything in Courses: course and module titles and descriptions, lesson titles and the text a lesson holds, concepts, glossary terms (their definitions and aliases), and resource labels and link titles.
  • A lesson is searched through what a learner can read. Its title, the text of its text blocks, an audio block’s transcript, and an older written lesson’s body. A quiz’s prompts, answers, explanations and stored JSON are never searched, so a quiz can never occupy a result slot or leak an answer, and a lesson whose only content is a quiz matches on its title alone.
  • Results are grouped by type and capped. A search answers with at most twenty results unless it asks for more, never more than fifty, taken fairly across the six types so one type cannot crowd the others out; the answer says when the cap cut it (which is what “Refine your search” reads).
  • Each result says what it is. Its type, its title, a one-line excerpt around the match (nothing when only the title matched), and the course — plus the lesson, for a lesson or a resource on one — so a screen knows what to open.
  • Retired courses are gone, and so is everything on them: their lessons, concepts, terms and resources. A soft-deleted term or resource never matches either.
  • A person sees only what they can open. Whoever is signed in is worked out by main, never sent by a screen. A learner finds courses they are enrolled in or own; a course builder or admin finds every course in their team’s workspace; in the personal workspace a person finds only the courses they own or are enrolled in, so a second account on the same computer sees none of the first’s. A request from nobody returns nothing rather than everything.
  • A concept or glossary term belongs to one workspace. A workspace-wide one is found only while you are in the workspace it was written in — your own personal workspace counts as one — and never from another team’s. Course-level concepts and terms are found wherever their course is.
  • A course’s own glossary word wins over the workspace definition of the same word, as everywhere else in Courses.
  • An agent finds the same answers without opening Courses. Omniscio's app-wide agent search (GET /search/all) carries a Courses source whenever the plugin is installed: it runs this one search under the same rule for who the person is, and each result says whether it is a course, module, lesson, concept, glossary term or resource, plus the course and lesson to open. It is the agent door only — Courses does not appear in the person's own Ctrl+K box. With the plugin not installed the source reads as off, and so does a person who holds no Courses role at all: a refusal is never dressed up as a failure to retry.
  • Where it lives: src/main/services/lms/search/ (index.ts the entry, queries.ts one statement per type, scope.ts the who-may-see-it rule, safe-text.ts the excerpt, types.ts the result shape). The bridge method is search, and an agent reaches the same answer at GET /lms/search?q=…&limit=…. The app-wide source itself is one defineSource({ id: 'lms' }) entry in src/main/services/cli/search/search-all-sources.ts.
  • What it costs: one scan of the text in the courses that person can open, capped per type. It is built for a person’s own library; a corpus large enough to be slow would need a separate search index, which this does not have.

The box itself (C6)

  • Ctrl+K or / opens it, from any screen inside Courses, and Escape closes it. It is the palette D3 describes: a box at the top of a dimmed screen, and a list under it.
  • Results are grouped by type — courses, modules, lessons, concepts, glossary, resources — with an “In this course” group first when the open screen sits inside a course (a learner’s lesson or course overview resolves its course through that person’s enrollment, so the group works there too). “In this course” is best-effort: the search answers one capped list across all six types, so a course with many matches can have some pushed out of it.
  • Arrows move, Enter opens, Escape closes, and the number of results is announced to a screen reader. What Enter opens depends on the person: a course builder or admin lands on the course or lesson editor; a learner lands on the course overview or the lesson. The box loads that person’s enrollments when it opens (and again before it opens a row whose course is not yet in that list), so a learner is never sent to the editor merely because the list had not loaded; a learner who genuinely holds no enrollment for a course keeps the editor, which is the only screen that shows a course they own. A concept opens its own screen, a term opens Glossary scoped to its course, a lesson resource opens its lesson, and a concept resource opens Concepts.
  • An empty box shows the current screen’s commands, then Recent and Go to. Recent holds the courses and concepts opened from this box (a lesson, term or resource has no by-id read to name it again, so it is not recorded), so it means “what you last opened from here”, not every visit in Courses. Go to lists the nine destinations the person’s role allows, each with its own key in the help overlay. The highlight rests on the first Recent or Go to row rather than the first command, so Ctrl+K then Enter still opens what it opened before; the arrow keys reach the commands above it.
  • States: searching, “Nothing in Courses matches”, an error with Try again, an offline line (search still reads this computer’s data, so being offline does not stop it), and “Refine your search” when the answer hit the cap. The footer carries D3’s hint to the app-wide box.
  • An empty box lists the current screen’s commands first. The screen that is open registers its commands while it is mounted: each row is the command’s own label with the key cap the person has for it, read from the shared key map and their own bindings, never from a second list. Only commands the person’s role may run appear, rows are in the key map’s own order however they registered, and a screen’s rows are gone the moment it closes — the box lists “the commands allowed here”, which is what D3 asks for. Enter (or a click) runs the highlighted command and closes the box; a command that opens a dialog opens it over the screen, not over the box. Typing still searches Courses rather than filtering the commands, so Enter is never ambiguous. A command whose handler needs the key press or the row the person had focused — moving a page block, answering or submitting the quiz, stepping through a list — is marked keyOnly in the key map and never becomes a row, because a row that silently does nothing is worse than no row; a command whose action is unavailable right now (a disabled Complete button, a draft that cannot be saved) is not registered until it is available. The app shell’s own commands (Search, Help, Back, Up one level) are not rows either: they are the box’s controls or already sit in Go to.
  • Where it lives: src/plugins/lms/web/src/components/search/ (search-model.ts the grouping, the role-aware targets, recents and the command section; LmsSearchPalette.tsx the overlay), the registry in src/plugins/lms/web/src/store/use-lms-command-registry-store.ts, and searchOpen in the overlay store plus the global.searchCourses handler in App.tsx.

The AI helper

A person can ask Courses a question about the lesson in front of them, or about a whole course, and get an answer drawn only from that course.

  • Answers come only from the course. A lesson ask is answered from the lesson on screen, the course's own description, its concepts and its glossary, plus any text the person selected, inside a 12,000-character budget. Where the course does not cover the question, the answer says so plainly instead of guessing.
  • A whole course can be asked, from a bounded outline. Asking with a course id and no lesson id answers from the course: its title and description, then each module's title and each lesson's title with a short excerpt — the lesson's own text blocks, cut at 240 characters per lesson, at most 40 lessons scanned, inside a 6,000-character outline section. That bound is deliberate: the model gets enough to say what the course covers and where, without every page body being sent. A course bigger than the bound is described from its first lessons, and the answer names the lesson an answer lives in rather than inventing the detail. Its sources name the course and at most eight of its lessons, so one answer never draws a forty-link list.
  • It never sees a quiz answer key. The context is built from the learner-safe page the person's own screen receives, which carries a quiz's prompts and choices but never its correct choice or its explanation. That holds for everyone, so even a course builder asking about a quiz never sends an answer key to the model.
  • A live quiz is off limits. For anyone who cannot edit the course, a quiz block is live until it is passed (must-pass) or submitted once (optional). While it is live, the helper removes its questions from the context and declines a question that repeats the quiz or asks for its answer — in plain words, and without spending anything. Someone who can edit the course is not restricted. A learner with no enrollment on the course counts as live, because nothing shows they have finished it. A course-wide ask keeps the same rule: its context carries no quiz block at all, and the decline is checked against every live quiz it scanned, with a sentence that says to finish that quiz in its lesson. That check is deliberately closer-matching than a lesson's, because a course-wide list of unfinished quizzes covers the very topics the course teaches: a course ask is declined only when it shares at least half a quiz's own question words, or one of them while asking to solve, pick or choose — so "where does the course cover mitochondria and ATP?" is answered while "which organelle makes ATP?" is not. The lock scan reads up to 200 lessons, so a quiz far past the 40-lesson outline cap is still locked; past 200 the answer is still safe, because a course ask never carries quiz text to answer from. A workspace ask is locked the same way, and its lock walks the courses the person is actually enrolled in rather than the 20 the answer lists — the answer list is about how much text fits, the lock is about not solving a quiz, and those two must not be the same number — at the same 200 lessons per course a lesson ask uses. Because that live set is far larger, the solving-word branch needs two shared words there instead of one, so "what is the correct way to escalate a ticket?" is answered while "which organelle should I pick?" is not. The residual is stated rather than hidden: past 20 enrolled courses, or past 200 lessons in one of them, a live quiz is not collected — and no answer key can leak regardless, because a workspace ask never carries quiz text at all.
  • It answers as the person asking. Main derives the person and their workspace; the glossary and concepts it may read are their own workspace's plus the course's, and a course's own word wins over the workspace's, as everywhere else in Courses.
  • Everything is billed and capped. The spend goes through the one LMS AI path with its own label, lms:helper, inside the plugin's daily AI cap, on the worker model tier — no second AI path and no model id in code.
  • Failure never breaks the lesson. No key, the cap reached, an unreachable service or an empty reply each come back as a finished sentence in answer, with the reason also in degradedReason. A refusal to help with a live quiz carries declined: true and its own reason.
  • Where it lives: src/main/services/lms/helper/ — index.ts is the service (it resolves a lesson target from a lesson id, a course target from a course id, or a workspace target from neither, and gathers live quizzes across a course or across the person's enrolled courses), context.ts builds the learner-safe lesson context, the course outline context and the workspace catalogue and owns the quiz lock, prompt.ts holds the instructions, including the course-scope and workspace-scope lines. A workspace target lists its courses through listCoursesInReach in src/main/services/lms/course-reach.ts, the bulk form of principalReachesCourse, and a reach-scoped concept read keeps a named concept honest. The bridge method is helperAsk; an agent reaches the same answer at POST /lms/helper/ask, which takes the full-trust key because it spends money.

Empty, loading and error states

Every Courses screen answers three questions the same way: what does it show while it is reading, when there is nothing to show, and when the read failed. One shared set does the answering, so a new screen inherits the behaviour instead of inventing it.

  • One set, in src/plugins/lms/web/src/components/states/. LoadingState draws skeleton rows for a list or a centred spinner for a pane; EmptyState is the plugin's existing block; ErrorState is a pane, or a banner that keeps already-loaded content visible, with Try again; ScreenState chooses between them for a screen that has all three. The parts they are built from (ui/EmptyState, ui/LoadingPanel, ListSkeleton) are unchanged — this is one import point, not a second set of components.
  • A list that has not loaded is never shown as empty. A first read in flight shows the loading idiom, and an empty state appears only once the read has answered with nothing.
  • A failed read is answered in plain words. The plugin bridge is not the app's IPC chokepoint, so humanizeErrorCopy is Courses' own boundary: a database code, a filesystem error or path, a provider response body, a stack trace or a bare 4xx/5xx becomes a sentence a person can act on, and a message already written for a person passes through untouched. It is applied where an error is rendered, so no screen can print a raw machine string.
  • A failed read is never dressed up as "not found". The course editor and lesson editor wait for their tree read to settle before they say something is missing, so a slow or failed load reads as loading or as an error, with a way to retry.
  • A screen that already has data keeps it. A refresh that fails shows the banner above the content rather than replacing the screen, so a builder never loses sight of their course because a background read failed.
  • The checklist test walks every screen. tests/unit/plugins/lms/lms-screen-states-checklist.test.tsx reads the view switch, fails when a screen is added without a case, and drives each one through a loading read, an empty answer and a failed read — including an assertion that the raw failure text never reaches the page.

Plugins in general — how they are installed, reviewed and enabled — are described on the Plugin marketplace page.

Last verified 2026-11-18