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/jobs/src/enqueue/index.ts

@@ -1,3 +1,4 @@
 export * from './media';
 export * from './emails';
 export * from './agent-course-generation';
+export * from './notifications';

packages/jobs/src/enqueue/notifications.ts

@@ -0,0 +1,51 @@
+import type { JobsOptions } from 'bullmq';
+
+import { JOB_NAMES, QUEUE_NAMES } from '../queues/names';
+import { QUEUE_DEFAULTS } from '../queues/defaults';
+import { getQueue } from '../queues/factories';
+import type { TNotifyCourseExercisePayload, TNotifyCourseSessionUpdatePayload } from '../payloads/notifications';
+
+/**
+ * Enqueue a `notifications:notify-course-exercise` job. Returns the BullMQ
+ * job id so the dashboard can poll its status. Each click is a fresh nudge,
+ * so we do NOT set a stable jobId (no dedupe across clicks).
+ */
+export async function enqueueNotifyCourseExercise(
+  payload: TNotifyCourseExercisePayload,
+  options: JobsOptions = {}
+): Promise<string | undefined> {
+  const job = await getQueue(QUEUE_NAMES.notifications).add(JOB_NAMES.notifications.notifyCourseExercise, payload, {
+    ...QUEUE_DEFAULTS[QUEUE_NAMES.notifications],
+    ...options
+  });
+
+  return job.id;
+}
+
+/** Enqueue a one-off run of the session-reminder scan (manual trigger / on-demand). */
+export async function enqueueSessionReminderScan(options: JobsOptions = {}): Promise<string | undefined> {
+  const job = await getQueue(QUEUE_NAMES.notifications).add(
+    JOB_NAMES.notifications.sessionReminderScan,
+    {},
+    { ...QUEUE_DEFAULTS[QUEUE_NAMES.notifications], ...options }
+  );
+
+  return job.id;
+}
+
+/** Enqueue a "session updated" notification that emails members an updated calendar invite. */
+export async function enqueueNotifyCourseSessionUpdate(
+  payload: TNotifyCourseSessionUpdatePayload,
+  options: JobsOptions = {}
+): Promise<string | undefined> {
+  const job = await getQueue(QUEUE_NAMES.notifications).add(
+    JOB_NAMES.notifications.notifyCourseSessionUpdate,
+    payload,
+    {
+      ...QUEUE_DEFAULTS[QUEUE_NAMES.notifications],
+      ...options
+    }
+  );
+
+  return job.id;
+}

packages/jobs/src/payloads/emails.ts

@@ -11,7 +11,9 @@ export const ZSendTemplateEmailPayload = z.object({
   to: z.string().email(),
   fields: z.record(z.string(), z.unknown()).default({}),
   from: z.string().optional(),
-  replyTo: z.string().optional()
+  replyTo: z.string().optional(),
+  /** Optional iCalendar (.ics) body attached as a text/calendar part. */
+  ics: z.string().optional()
 });
 export type TSendTemplateEmailPayload = z.infer<typeof ZSendTemplateEmailPayload>;
 

packages/jobs/src/payloads/index.ts

@@ -2,3 +2,4 @@ export * from './media';
 export * from './emails';
 export * from './maintenance';
 export * from './agent-course-generation';
+export * from './notifications';

packages/jobs/src/payloads/notifications.ts

@@ -0,0 +1,49 @@
+import * as z from 'zod';
+
+/**
+ * Org branding carried through to the `quizAssigned` email. Mirrors
+ * `@cio/email`'s `ZEmailBranding`; defined inline so this lean queue package
+ * doesn't take a dependency on the email package. Re-validated against the
+ * email template schema at send time.
+ */
+const ZNotifyBranding = z
+  .object({
+    orgName: z.string().optional(),
+    logoUrl: z.string().url().optional(),
+    themeColor: z
+      .string()
+      .regex(/^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/)
+      .optional()
+  })
+  .optional();
+
+/**
+ * Payload for a `notifications:notify-course-exercise` job. Fired when a
+ * teacher clicks "Notify students" on an exercise — the worker fans out one
+ * `quizAssigned` email per course member with a deep link to take the quiz.
+ */
+export const ZNotifyCourseExercisePayload = z.object({
+  courseId: z.string().min(1),
+  exerciseTitle: z.string().min(1),
+  courseName: z.string().min(1),
+  orgName: z.string().min(1),
+  fromName: z.string().min(1),
+  quizUrl: z.string().min(1),
+  branding: ZNotifyBranding
+});
+export type TNotifyCourseExercisePayload = z.infer<typeof ZNotifyCourseExercisePayload>;
+
+/** Periodic scan that emails 24h/1h reminders for upcoming live sessions. No payload. */
+export const ZSessionReminderScanPayload = z.object({}).default({});
+export type TSessionReminderScanPayload = z.infer<typeof ZSessionReminderScanPayload>;
+
+/**
+ * Payload for a `notifications:notify-course-session-update` job. Fired when a
+ * teacher changes a live lesson's time/link — emails every member an updated
+ * calendar invite (same UID, higher SEQUENCE).
+ */
+export const ZNotifyCourseSessionUpdatePayload = z.object({
+  courseId: z.string().min(1),
+  lessonId: z.string().min(1)
+});
+export type TNotifyCourseSessionUpdatePayload = z.infer<typeof ZNotifyCourseSessionUpdatePayload>;

packages/jobs/src/queues/index.ts

@@ -1,3 +1,4 @@
 export * from './names';
 export * from './defaults';
 export * from './factories';
+export * from './job-state';

packages/jobs/src/queues/job-state.ts

@@ -0,0 +1,56 @@
+import { getQueue } from './factories';
+import type { QueueName } from './names';
+import { JOB_STATUS, type JobEnvelope, type JobStatus, suggestNextPollMs } from '../status';
+
+function mapBullState(state: string): JobStatus {
+  switch (state) {
+    case 'completed':
+      return JOB_STATUS.completed;
+    case 'failed':
+      return JOB_STATUS.failed;
+    case 'active':
+      return JOB_STATUS.running;
+    default:
+      // waiting | waiting-children | delayed | prioritized | paused
+      return JOB_STATUS.queued;
+  }
+}
+
+/**
+ * Read a queued job's status as a `JobEnvelope` directly from BullMQ — no DB
+ * ledger. Used by domains (e.g. notify-course-exercise) that don't need a
+ * durable run history, just "is it done yet?" polling. Returns null if the
+ * job no longer exists (e.g. retention swept it).
+ */
+export async function getQueueJobEnvelope(
+  queueName: QueueName,
+  jobId: string,
+  domain: string,
+  pollCount = 0
+): Promise<JobEnvelope | null> {
+  const job = await getQueue(queueName).getJob(jobId);
+  if (!job) {
+    return null;
+  }
+
+  const status = mapBullState(await job.getState());
+  const finishedOn = job.finishedOn ?? job.processedOn ?? job.timestamp;
+
+  return {
+    job: {
+      id: String(job.id),
+      domain,
+      status,
+      stage: null,
+      progressPercent: typeof job.progress === 'number' ? job.progress : null,
+      createdAt: new Date(job.timestamp).toISOString(),
+      updatedAt: new Date(finishedOn).toISOString(),
+      result: (job.returnvalue as Record<string, unknown> | null) ?? null,
+      error: job.failedReason ? { code: 'JOB_FAILED', message: job.failedReason } : null,
+      attempt: job.attemptsMade,
+      maxAttempts: job.opts.attempts ?? 1
+    },
+    events: [],
+    nextPollMs: suggestNextPollMs(status, pollCount)
+  };
+}

packages/jobs/src/queues/names.ts

@@ -33,6 +33,11 @@ export const JOB_NAMES = {
   emails: {
     send: 'send'
   },
+  notifications: {
+    notifyCourseExercise: 'notify-course-exercise',
+    sessionReminderScan: 'session-reminder-scan',
+    notifyCourseSessionUpdate: 'notify-course-session-update'
+  },
   webhooks: {
     deliver: 'deliver'
   },