feat: live class sessions, CE workflow, and docs (#683)

Adds live-class session scheduling on lessons (join link, date/time,
timezone) with automatic 24h and 1h reminder emails plus a calendar
invite (.ics), a time-change notification with an updated invite, a
teacher-authored welcome email and session invite on enrollment, and a
"Notify students" quiz nudge.

LMS gets an upcoming live-sessions card and Join buttons, plus a
reusable live-session card component (3 states) in @cio/ui with a
Storybook story. The sidebar content tree now reflects sequential
progression locking like the content list, and the course-completion
confetti regression is fixed.

Org-based emails no longer reference ClassroomIO by name. Docs add
live-class, welcome-email, and course-progression guides, expand the
certificates guide (design, signatures, corrected labels), move
plan-required callouts to the top, flatten how-to-guides to the docs
root with redirects, and add screenshots. Includes an add-docs-image
skill.

packages/db/src/queries/course/course.ts

@@ -16,6 +16,7 @@ import { and, count, desc, eq, ilike, inArray, isNotNull, isNull, or, sql } from
 import { ROLE } from '@cio/utils/constants';
 import { db, type DbOrTxClient } from '@db/drizzle';
 import { getCourseContentItems, type CourseContentItemRow } from './content';
+import { getUpcomingSessionsForCourseIds, type CourseUpcomingSession } from './session';
 
 /**
  * Base course type - extends TCourse with lessonCount
@@ -42,10 +43,12 @@ export interface TAdminCourse extends TBaseCourse {
 export interface TStudentCourse extends TBaseCourse {
   progressRate: number;
   exercisesCompleted: number;
+  certificateEarnedAt: string | null;
   complianceStatus: string | null;
   complianceCycleNumber: number | null;
   complianceDueDate: string | null;
   complianceValidUntil: string | null;
+  upcomingSession: CourseUpcomingSession | null;
 }
 
 /**
@@ -305,6 +308,7 @@ export type CourseWithRelations = TCourse & {
     customDomain: string | null;
     isCustomDomainVerified: boolean | null;
     theme: string | null;
+    avatarUrl: string | null;
     settings: (typeof schema.organization.$inferSelect)['settings'];
   } | null;
 };
@@ -350,6 +354,7 @@ export async function getCourseWithRelations(
         customDomain: string | null;
         isCustomDomainVerified: boolean | null;
         theme: string | null;
+        avatarUrl: string | null;
         settings: (typeof schema.organization.$inferSelect)['settings'];
       } | null;
     };
@@ -373,6 +378,7 @@ export async function getCourseWithRelations(
               customDomain: schema.organization.customDomain,
               isCustomDomainVerified: schema.organization.isCustomDomainVerified,
               theme: schema.organization.theme,
+              avatarUrl: schema.organization.avatarUrl,
               settings: schema.organization.settings
             }
           })
@@ -416,6 +422,7 @@ export async function getCourseWithRelations(
             customDomain: groupData[0].organization.customDomain ?? null,
             isCustomDomainVerified: groupData[0].organization.isCustomDomainVerified ?? null,
             theme: groupData[0].organization.theme ?? null,
+            avatarUrl: groupData[0].organization.avatarUrl ?? null,
             settings: groupData[0].organization.settings ?? null
           }
         : null;
@@ -633,6 +640,8 @@ export type TCourseCertificationRow = {
   orgCustomDomain: string | null;
   orgIsCustomDomainVerified: boolean | null;
   orgName: string;
+  orgAvatarUrl: string | null;
+  orgTheme: string | null;
 };
 
 export async function getCourseCertificationRow(courseId: string): Promise<TCourseCertificationRow | null> {
@@ -646,7 +655,9 @@ export async function getCourseCertificationRow(courseId: string): Promise<TCour
         orgSiteName: schema.organization.siteName,
         orgCustomDomain: schema.organization.customDomain,
         orgIsCustomDomainVerified: schema.organization.isCustomDomainVerified,
-        orgName: schema.organization.name
+        orgName: schema.organization.name,
+        orgAvatarUrl: schema.organization.avatarUrl,
+        orgTheme: schema.organization.theme
       })
       .from(schema.course)
       .innerJoin(schema.group, eq(schema.course.groupId, schema.group.id))
@@ -955,6 +966,7 @@ export const getEnrolledCourses = async ({
             sql`gm.profile_id = ${sql.raw(`'${profileId}'::uuid`)}`
           )}
         )`.as('exercises_completed'),
+        certificateEarnedAt: schema.groupmember.certificateEarnedAt,
         complianceStatus: schema.courseCompletionRecord.status,
         complianceCycleNumber: schema.courseCompletionRecord.cycleNumber,
         complianceDueDate: schema.courseCompletionRecord.dueDate,
@@ -1002,16 +1014,21 @@ export const getEnrolledCourses = async ({
       .groupBy(schema.course.id, schema.courseCompletionRecord.id)
       .orderBy(desc(schema.course.createdAt));
 
+    const liveCourseIds = result.filter((row) => row.course.type === 'LIVE_CLASS').map((row) => row.course.id);
+    const upcomingByCourse = await getUpcomingSessionsForCourseIds(liveCourseIds);
+
     return result.map((row) => ({
       ...row.course,
       lessonCount: Number(row.lessonCount),
       progressRate: Number(row.progressRate),
       exerciseCount: Number(row.exerciseCount),
       exercisesCompleted: Number(row.exercisesCompleted),
+      certificateEarnedAt: row.certificateEarnedAt ?? null,
       complianceStatus: row.complianceStatus ?? null,
       complianceCycleNumber: row.complianceCycleNumber ?? null,
       complianceDueDate: row.complianceDueDate ?? null,
-      complianceValidUntil: row.complianceValidUntil ?? null
+      complianceValidUntil: row.complianceValidUntil ?? null,
+      upcomingSession: upcomingByCourse.get(row.course.id) ?? null
     }));
   } catch (error) {
     console.error('getEnrolledCourses error:', error);
@@ -1122,7 +1139,10 @@ export async function getCourseWithOrgData(courseId: string): Promise<{
   orgSiteName: string | null;
   orgCustomDomain: string | null;
   orgIsCustomDomainVerified: boolean | null;
+  orgAvatarUrl: string | null;
+  orgTheme: string | null;
   groupId: string | null;
+  welcomeEmailMessage: string | null;
 } | null> {
   try {
     const result = await db
@@ -1132,7 +1152,10 @@ export async function getCourseWithOrgData(courseId: string): Promise<{
         orgSiteName: schema.organization.siteName,
         orgCustomDomain: schema.organization.customDomain,
         orgIsCustomDomainVerified: schema.organization.isCustomDomainVerified,
-        groupId: schema.course.groupId
+        orgAvatarUrl: schema.organization.avatarUrl,
+        orgTheme: schema.organization.theme,
+        groupId: schema.course.groupId,
+        metadata: schema.course.metadata
       })
       .from(schema.course)
       .innerJoin(schema.group, eq(schema.course.groupId, schema.group.id))
@@ -1144,7 +1167,9 @@ export async function getCourseWithOrgData(courseId: string): Promise<{
       return null;
     }
 
-    return result[0];
+    const { metadata, ...rest } = result[0];
+
+    return { ...rest, welcomeEmailMessage: metadata?.welcomeEmailMessage ?? null };
   } catch (error) {
     console.error('getCourseWithOrgData error:', error);
     throw new Error(
@@ -1332,15 +1357,21 @@ export async function getOrgCourseGroups(orgId: string, courseIds: string[]) {
   try {
     if (courseIds.length === 0) return [];
 
-    return db
+    const rows = await db
       .select({
         courseId: schema.course.id,
         courseTitle: schema.course.title,
-        groupId: schema.course.groupId
+        groupId: schema.course.groupId,
+        metadata: schema.course.metadata
       })
       .from(schema.course)
       .innerJoin(schema.group, eq(schema.course.groupId, schema.group.id))
       .where(and(eq(schema.group.organizationId, orgId), inArray(schema.course.id, courseIds)));
+
+    return rows.map(({ metadata, ...rest }) => ({
+      ...rest,
+      welcomeEmailMessage: metadata?.welcomeEmailMessage ?? null
+    }));
   } catch (error) {
     console.error('getOrgCourseGroups error:', error);
     throw new Error(`Failed to get org course groups: ${error instanceof Error ? error.message : 'Unknown error'}`);

packages/db/src/queries/course/index.ts

@@ -6,3 +6,4 @@ export * from './content-batch';
 export * from './people';
 export * from './invite';
 export * from './public-course';
+export * from './session';

packages/db/src/queries/course/invite.ts

@@ -350,6 +350,8 @@ export type TCourseInviteAcceptBundle = {
     siteName: string;
     customDomain: string | null;
     isCustomDomainVerified: boolean | null;
+    avatarUrl: string | null;
+    theme: string | null;
   };
 };
 
@@ -374,7 +376,9 @@ export async function selectCourseInviteAcceptBundleByTokenHash(
           name: schema.organization.name,
           siteName: schema.organization.siteName,
           customDomain: schema.organization.customDomain,
-          isCustomDomainVerified: schema.organization.isCustomDomainVerified
+          isCustomDomainVerified: schema.organization.isCustomDomainVerified,
+          avatarUrl: schema.organization.avatarUrl,
+          theme: schema.organization.theme
         }
       })
       .from(schema.courseInvite)

packages/db/src/queries/course/session.ts

@@ -0,0 +1,161 @@
+import * as schema from '@db/schema';
+
+import { and, eq, gt, inArray, isNotNull, lt } from 'drizzle-orm';
+
+import { ROLE } from '@cio/utils/constants';
+import { db } from '@db/drizzle';
+
+export type UpcomingSessionReminderRow = {
+  courseId: string;
+  courseName: string;
+  sessionTimezone: string | null;
+  lessonId: string;
+  lessonTitle: string;
+  lessonAt: string;
+  callUrl: string;
+  profileId: string;
+  email: string | null;
+  organizationName: string;
+  organizationSiteName: string | null;
+  organizationCustomDomain: string | null;
+  organizationIsCustomDomainVerified: boolean | null;
+  organizationAvatarUrl: string | null;
+  organizationTheme: string | null;
+};
+
+/**
+ * Lessons that are live sessions (have a `callUrl`) starting within the next
+ * ~25h, on a published/active LIVE_CLASS course, joined to each enrolled
+ * student + org branding. One row per (session × student) for the reminder scan.
+ */
+export async function listUpcomingSessionsForReminderScan(): Promise<UpcomingSessionReminderRow[]> {
+  try {
+    const now = new Date();
+    const horizon = new Date(now.getTime() + 25 * 60 * 60 * 1000);
+
+    const result = await db
+      .select({
+        courseId: schema.course.id,
+        courseName: schema.course.title,
+        courseMetadata: schema.course.metadata,
+        lessonId: schema.lesson.id,
+        lessonTitle: schema.lesson.title,
+        lessonAt: schema.lesson.lessonAt,
+        callUrl: schema.lesson.callUrl,
+        profileId: schema.groupmember.profileId,
+        email: schema.profile.email,
+        organizationName: schema.organization.name,
+        organizationSiteName: schema.organization.siteName,
+        organizationCustomDomain: schema.organization.customDomain,
+        organizationIsCustomDomainVerified: schema.organization.isCustomDomainVerified,
+        organizationAvatarUrl: schema.organization.avatarUrl,
+        organizationTheme: schema.organization.theme
+      })
+      .from(schema.lesson)
+      .innerJoin(schema.course, eq(schema.lesson.courseId, schema.course.id))
+      .innerJoin(schema.group, eq(schema.course.groupId, schema.group.id))
+      .innerJoin(schema.organization, eq(schema.group.organizationId, schema.organization.id))
+      .innerJoin(schema.groupmember, eq(schema.groupmember.groupId, schema.group.id))
+      .leftJoin(schema.profile, eq(schema.groupmember.profileId, schema.profile.id))
+      .where(
+        and(
+          eq(schema.course.type, 'LIVE_CLASS'),
+          eq(schema.course.status, 'ACTIVE'),
+          eq(schema.course.isPublished, true),
+          eq(schema.groupmember.roleId, ROLE.STUDENT),
+          isNotNull(schema.lesson.callUrl),
+          isNotNull(schema.lesson.lessonAt),
+          gt(schema.lesson.lessonAt, now.toISOString()),
+          lt(schema.lesson.lessonAt, horizon.toISOString())
+        )
+      );
+
+    return result
+      .filter((row) => row.profileId && row.lessonAt && row.callUrl)
+      .map((row) => ({
+        courseId: row.courseId,
+        courseName: row.courseName,
+        sessionTimezone: row.courseMetadata?.sessionTimezone ?? null,
+        lessonId: row.lessonId,
+        lessonTitle: row.lessonTitle,
+        lessonAt: row.lessonAt!,
+        callUrl: row.callUrl!,
+        profileId: row.profileId!,
+        email: row.email,
+        organizationName: row.organizationName,
+        organizationSiteName: row.organizationSiteName,
+        organizationCustomDomain: row.organizationCustomDomain,
+        organizationIsCustomDomainVerified: row.organizationIsCustomDomainVerified,
+        organizationAvatarUrl: row.organizationAvatarUrl,
+        organizationTheme: row.organizationTheme
+      }));
+  } catch (error) {
+    console.error('listUpcomingSessionsForReminderScan error:', error);
+    throw new Error(
+      `Failed to list upcoming sessions for reminder scan: ${error instanceof Error ? error.message : 'Unknown error'}`
+    );
+  }
+}
+
+export type CourseUpcomingSession = {
+  lessonId: string;
+  lessonTitle: string;
+  callUrl: string;
+  lessonAt: string;
+  sessionTimezone: string | null;
+};
+
+/**
+ * The next upcoming live session (earliest future lesson with a `callUrl`) for
+ * each of the given course ids. Used to show a "Join session" button on /lms.
+ */
+export async function getUpcomingSessionsForCourseIds(
+  courseIds: string[]
+): Promise<Map<string, CourseUpcomingSession>> {
+  try {
+    if (courseIds.length === 0) return new Map();
+
+    const now = new Date().toISOString();
+
+    const rows = await db
+      .select({
+        courseId: schema.lesson.courseId,
+        courseMetadata: schema.course.metadata,
+        lessonId: schema.lesson.id,
+        lessonTitle: schema.lesson.title,
+        callUrl: schema.lesson.callUrl,
+        lessonAt: schema.lesson.lessonAt
+      })
+      .from(schema.lesson)
+      .innerJoin(schema.course, eq(schema.lesson.courseId, schema.course.id))
+      .where(
+        and(
+          inArray(schema.lesson.courseId, courseIds),
+          isNotNull(schema.lesson.callUrl),
+          isNotNull(schema.lesson.lessonAt),
+          gt(schema.lesson.lessonAt, now)
+        )
+      )
+      .orderBy(schema.lesson.lessonAt);
+
+    const byCourse = new Map<string, CourseUpcomingSession>();
+    for (const row of rows) {
+      if (!row.callUrl || !row.lessonAt) continue;
+      // rows are ascending by lessonAt; keep the first (earliest) per course.
+      if (byCourse.has(row.courseId)) continue;
+
+      byCourse.set(row.courseId, {
+        lessonId: row.lessonId,
+        lessonTitle: row.lessonTitle,
+        callUrl: row.callUrl,
+        lessonAt: row.lessonAt,
+        sessionTimezone: row.courseMetadata?.sessionTimezone ?? null
+      });
+    }
+
+    return byCourse;
+  } catch (error) {
+    console.error('getUpcomingSessionsForCourseIds error:', error);
+    throw new Error(`Failed to get upcoming sessions: ${error instanceof Error ? error.message : 'Unknown error'}`);
+  }
+}

packages/db/src/queries/newsfeed/newsfeed.ts

@@ -2,6 +2,7 @@ import * as schema from '@db/schema';
 
 import type { TCourseNewsfeed, TCourseNewsfeedComment, TNewCourseNewsfeed, TNewCourseNewsfeedComment } from '@db/types';
 import { and, db, desc, eq, lt, ne, sql } from '@db/drizzle';
+import { ROLE } from '@cio/utils/constants';
 
 /**
  * Gets newsfeed items by course ID
@@ -400,6 +401,8 @@ export async function getNewsfeedForEmail(
   organization: {
     name: string | null;
     siteName: string | null;
+    avatarUrl: string | null;
+    theme: string | null;
   } | null;
   courseMembers: Array<{
     email: string | null;
@@ -431,7 +434,7 @@ export async function getNewsfeedForEmail(
     const row = result[0];
 
     // Get all course members (excluding author if specified)
-    const memberConditions = [eq(schema.course.id, row.course.id)];
+    const memberConditions = [eq(schema.course.id, row.course.id), eq(schema.groupmember.roleId, ROLE.STUDENT)];
     if (excludeAuthorId) {
       memberConditions.push(ne(schema.groupmember.id, excludeAuthorId));
     }
@@ -460,7 +463,9 @@ export async function getNewsfeedForEmail(
         : null,
       organization: {
         name: row.organization.name,
-        siteName: row.organization.siteName
+        siteName: row.organization.siteName,
+        avatarUrl: row.organization.avatarUrl,
+        theme: row.organization.theme
       },
       courseMembers: membersResult
         .filter((m) => m.profile?.email) // Only include members with email

packages/db/src/queries/program/goal.ts

@@ -106,6 +106,8 @@ export async function listAssignmentsForReminderScan(): Promise<
     organizationSiteName: string | null;
     organizationCustomDomain: string | null;
     organizationIsCustomDomainVerified: boolean | null;
+    organizationAvatarUrl: string | null;
+    organizationTheme: string | null;
   }>
 > {
   try {
@@ -120,7 +122,9 @@ export async function listAssignmentsForReminderScan(): Promise<
         organizationName: schema.organization.name,
         organizationSiteName: schema.organization.siteName,
         organizationCustomDomain: schema.organization.customDomain,
-        organizationIsCustomDomainVerified: schema.organization.isCustomDomainVerified
+        organizationIsCustomDomainVerified: schema.organization.isCustomDomainVerified,
+        organizationAvatarUrl: schema.organization.avatarUrl,
+        organizationTheme: schema.organization.theme
       })
       .from(schema.programGoalAssignment)
       .innerJoin(schema.programMember, eq(schema.programGoalAssignment.programMemberId, schema.programMember.id))
@@ -146,7 +150,9 @@ export async function listAssignmentsForReminderScan(): Promise<
         organizationName: row.organizationName,
         organizationSiteName: row.organizationSiteName,
         organizationCustomDomain: row.organizationCustomDomain,
-        organizationIsCustomDomainVerified: row.organizationIsCustomDomainVerified
+        organizationIsCustomDomainVerified: row.organizationIsCustomDomainVerified,
+        organizationAvatarUrl: row.organizationAvatarUrl,
+        organizationTheme: row.organizationTheme
       }));
   } catch (error) {
     console.error('listAssignmentsForReminderScan error:', error);

packages/db/src/schema.ts

@@ -687,6 +687,10 @@ export const course = pgTable(
       grading?: boolean;
       lessonDownload?: boolean;
       allowNewStudent: boolean;
+      /** Teacher-authored HTML sent in the welcome email after a student enrolls. */
+      welcomeEmailMessage?: string | null;
+      /** IANA timezone for this course's live sessions (display + scheduling). */
+      sessionTimezone?: string | null;
       sectionDisplay?: Record<string, boolean>;
       isContentGroupingEnabled?: boolean;
       /** `free` = all unlocked content is accessible; `sequential` = prior items must be complete. */