feat: HLS streaming, transcripts, agent course generation & landing-page course previews (#663)

New features:
- HLS video encoding/streaming (hls routes, hls-encoder) and a media
  transcripts pipeline (transcripts route + media-transcript queries)
- AI assistant chat vs. run model: agent-course-generation worker/queue,
  run-monitor pane, chat-changes card, content ask-ai bar
- Per-theme course-page previews across org landing-page themes (bold,
  classic, corporate, editorial, etc.) with a shared course token/component set
- View-as-student mode and login-link / link-invite invite flows

Refactor:
- Extract packages/core consolidating config (env, storage, dashboard-url),
  services and utils previously duplicated under apps/api/src/config
- Remove legacy agent service modules (chat-tools, chat-context,
  context-window, document, fetch-url, lesson-content)
- Relax Cross-Origin-Resource-Policy to allow cross-origin media embedding
- Add format script to tenant-router so turbo run format covers it

packages/utils/src/errors/index.ts

@@ -0,0 +1,29 @@
+import { ErrorCodes, type ErrorCode } from '../constants';
+
+export { ErrorCodes, type ErrorCode };
+
+/**
+ * Standard HTTP status code value. Kept as a structural `number` so this
+ * module stays free of HTTP-framework deps (hono). The api layer narrows
+ * this when handing the value to its response helpers.
+ */
+export type AppErrorStatusCode = number;
+
+/**
+ * Standard application error with code for easy identification.
+ *
+ * Lives in `@cio/utils/errors` so it can be thrown from any workspace package
+ * (notably `@cio/core`) without those packages depending on `@cio/api`.
+ * HTTP-shaped helpers like `handleError` stay in `@cio/api`.
+ */
+export class AppError extends Error {
+  constructor(
+    error: string | Error,
+    public code: string,
+    public statusCode: AppErrorStatusCode = 500,
+    public field?: string
+  ) {
+    super(error instanceof Error ? error.message : error);
+    this.name = 'AppError';
+  }
+}

packages/utils/src/functions/index.ts

@@ -2,3 +2,4 @@ export * from './array';
 export * from './fileValidation';
 export * from './sanitize';
 export * from './slug';
+export * from './transcript-vtt';

packages/utils/src/functions/transcript-vtt.ts

@@ -0,0 +1,45 @@
+export interface TranscriptVttSegment {
+  start: number;
+  end: number;
+  text: string;
+}
+
+function formatVttTime(seconds: number): string {
+  if (!Number.isFinite(seconds) || seconds < 0) {
+    seconds = 0;
+  }
+
+  const totalMs = Math.round(seconds * 1000);
+  const hours = Math.floor(totalMs / 3_600_000);
+  const minutes = Math.floor((totalMs % 3_600_000) / 60_000);
+  const secs = Math.floor((totalMs % 60_000) / 1000);
+  const ms = totalMs % 1000;
+
+  const pad = (n: number, width: number) => n.toString().padStart(width, '0');
+
+  return `${pad(hours, 2)}:${pad(minutes, 2)}:${pad(secs, 2)}.${pad(ms, 3)}`;
+}
+
+/**
+ * Build a minimal WEBVTT caption file from transcript segment timestamps.
+ */
+export function segmentsToWebVtt(segments: TranscriptVttSegment[]): string {
+  const lines = ['WEBVTT', ''];
+
+  let cueIndex = 1;
+  for (const segment of segments) {
+    const text = segment.text.trim();
+    if (!text) continue;
+
+    const start = formatVttTime(segment.start);
+    const end = formatVttTime(Math.max(segment.end, segment.start + 0.001));
+
+    lines.push(String(cueIndex));
+    lines.push(`${start} --> ${end}`);
+    lines.push(text);
+    lines.push('');
+    cueIndex++;
+  }
+
+  return lines.join('\n');
+}

packages/utils/src/license/index.ts

@@ -1 +1,2 @@
 export * from './constants';
+export * from './plan-features';

packages/utils/src/license/plan-features.ts

@@ -0,0 +1,33 @@
+import { PLAN } from '../plans/constants';
+import { LICENSE_FEATURE, type LicenseFeatureId } from './constants';
+
+type OrgPlan = {
+  planName: string | null;
+  isActive: boolean | null;
+};
+
+export function getActivePlanName(plans: OrgPlan[] | undefined | null): string | null {
+  const activePlan = plans?.find((plan) => plan.isActive);
+
+  return activePlan?.planName ?? null;
+}
+
+/**
+ * Maps a cloud organization plan to dashboard license feature IDs.
+ * Self-hosted instances use instance-level license keys instead.
+ */
+export function getLicenseFeaturesForPlan(planName: string | null | undefined): LicenseFeatureId[] {
+  if (!planName || planName === PLAN.BASIC) {
+    return [];
+  }
+
+  if (planName === PLAN.EARLY_ADOPTER) {
+    return [LICENSE_FEATURE.CUSTOM_DOMAIN, LICENSE_FEATURE.CUSTOM_BRANDING];
+  }
+
+  if (planName === PLAN.ENTERPRISE) {
+    return Object.values(LICENSE_FEATURE);
+  }
+
+  return [];
+}

packages/utils/src/validation/assets/assets.ts

@@ -125,3 +125,67 @@ export const ZAssetThumbnailSelect = z.object({
   thumbnailUrl: z.string().url()
 });
 export type TAssetThumbnailSelect = z.infer<typeof ZAssetThumbnailSelect>;
+
+// --- HLS upload lifecycle ---
+
+export const ZInitHlsAsset = z.object({
+  fileName: z.string().min(1),
+  byteSize: z.coerce.number().int().min(0),
+  mimeType: z.string().min(1),
+  title: z.string().optional()
+});
+export type TInitHlsAsset = z.infer<typeof ZInitHlsAsset>;
+
+/**
+ * Batch-presign request. Caller passes a list of relative paths under
+ * `videos/{assetId}/` that the browser encoder is about to write.
+ * The server returns presigned PUT URLs keyed by the same relative path.
+ */
+export const ZBatchPresignHls = z.object({
+  paths: z.array(z.string().min(1).max(256)).min(1).max(2000),
+  contentTypeByExtension: z.record(z.string().regex(/^\.[a-z0-9]+$/), z.string().min(1)).optional()
+});
+export type TBatchPresignHls = z.infer<typeof ZBatchPresignHls>;
+
+export const ZHls1080Status = z.enum(['none', 'generating', 'ready', 'failed']);
+export type THls1080Status = z.infer<typeof ZHls1080Status>;
+
+export const ZFinalizeHlsAsset = z.object({
+  manifestKey: z.string().min(1),
+  audioKey: z.string().min(1).optional(),
+  durationSeconds: z.coerce.number().min(0),
+  aspectRatio: z.string().optional(),
+  byteSize: z.coerce.number().int().min(0),
+  videoCodec: z.string().optional(),
+  audioCodec: z.string().optional(),
+  sourceWidth: z.coerce.number().int().min(1).optional(),
+  sourceHeight: z.coerce.number().int().min(1).optional(),
+  hlsRenditions: z.array(z.string().min(1)).optional(),
+  hls1080Status: ZHls1080Status.optional(),
+  /**
+   * Fully-qualified thumbnail URLs returned by the dashboard after uploading
+   * candidates through the existing `/media/image` endpoint. We persist them
+   * as-is — no key→URL prefixing — because that endpoint already returns
+   * a public URL.
+   */
+  thumbnailUrl: z.string().url().optional(),
+  thumbnailCandidateUrls: z.array(z.string().url()).optional(),
+  title: z.string().optional()
+});
+export type TFinalizeHlsAsset = z.infer<typeof ZFinalizeHlsAsset>;
+
+/** Presign paths for a manual p1080 rendition on an active HLS asset. */
+export const ZBatchPresignHls1080 = ZBatchPresignHls;
+export type TBatchPresignHls1080 = z.infer<typeof ZBatchPresignHls1080>;
+
+export const ZFinalizeHls1080 = z.object({
+  additionalByteSize: z.coerce.number().int().min(0).default(0),
+  sourceWidth: z.coerce.number().int().min(1).optional(),
+  sourceHeight: z.coerce.number().int().min(1).optional()
+});
+export type TFinalizeHls1080 = z.infer<typeof ZFinalizeHls1080>;
+
+export const ZHlsCookieParam = z.object({
+  assetId: z.string().min(1)
+});
+export type THlsCookieParam = z.infer<typeof ZHlsCookieParam>;

packages/utils/src/validation/course/course.ts

@@ -315,6 +315,8 @@ export const ZCourseMetadata = z.object({
   instructor: ZCourseInstructor.optional(),
   certificate: ZCourseCertificate.optional(),
   reviews: z.array(ZCourseReview).optional(),
+  skills: z.array(z.string().min(1).max(80)).max(60).optional(),
+  tools: z.array(z.string().min(1).max(80)).max(60).optional(),
   lessonTabsOrder: ZCourseLessonTabsOrder.optional(),
   grading: z.boolean().optional(),
   lessonDownload: z.boolean().optional(),
@@ -336,6 +338,8 @@ export const ZCourseLandingPageMetadataUpdate = z.object({
   instructor: ZCourseInstructor.partial().optional(),
   certificate: ZCourseCertificate.partial().optional(),
   reviews: z.array(ZCourseReview).optional(),
+  skills: z.array(z.string().min(1).max(80)).max(60).optional(),
+  tools: z.array(z.string().min(1).max(80)).max(60).optional(),
   lessonTabsOrder: ZCourseLessonTabsOrder.optional(),
   grading: z.boolean().optional(),
   lessonDownload: z.boolean().optional(),

packages/utils/src/validation/media/media.ts

@@ -26,3 +26,8 @@ export const ZTranscriptResponse = z.object({
   durationSeconds: z.number().nullable()
 });
 export type TTranscriptResponse = z.infer<typeof ZTranscriptResponse>;
+
+export const ZUpdateTranscript = z.object({
+  segments: z.array(ZTranscriptSegment).min(1)
+});
+export type TUpdateTranscript = z.infer<typeof ZUpdateTranscript>;

packages/utils/src/validation/organization/organization.ts

@@ -18,7 +18,9 @@ export type TGetOrganizations = z.infer<typeof ZGetOrganizations>;
 
 export const ZGetCoursesBySiteName = z.object({
   siteName: z.string().min(1),
-  tags: z.string().optional()
+  tags: z.string().optional(),
+  page: z.coerce.number().int().min(1).optional(),
+  limit: z.coerce.number().int().min(1).max(100).optional()
 });
 
 export type TGetCoursesBySiteName = z.infer<typeof ZGetCoursesBySiteName>;
@@ -128,6 +130,18 @@ export const ZRemoveTeamMember = z.object({
 
 export type TRemoveTeamMember = z.infer<typeof ZRemoveTeamMember>;
 
+export const ZCreateLinkInvite = z.object({
+  roleId: z.number().int().positive()
+});
+
+export type TCreateLinkInvite = z.infer<typeof ZCreateLinkInvite>;
+
+export const ZToggleLinkInvite = z.object({
+  isRevoked: z.boolean()
+});
+
+export type TToggleLinkInvite = z.infer<typeof ZToggleLinkInvite>;
+
 export const ZGetUserAnalytics = z.object({
   userId: z.uuid()
 });