From 4e498cb27b1d5b3bff81394914310c445c893a2f Mon Sep 17 00:00:00 2001
From: NiloCK <colin@mrkennedy.ca>
Date: Wed, 12 Nov 2025 15:26:18 -0400
Subject: [PATCH 1/5] add crsID <> dependencyName mapping

---
 .../src/impl/static/StaticDataLayerProvider.ts  |  2 +-
 packages/db/src/impl/static/coursesDB.ts        | 17 +++++++++++++++--
 2 files changed, 16 insertions(+), 3 deletions(-)

diff --git a/packages/db/src/impl/static/StaticDataLayerProvider.ts b/packages/db/src/impl/static/StaticDataLayerProvider.ts
index 7edb9adba..c40232a1d 100644
--- a/packages/db/src/impl/static/StaticDataLayerProvider.ts
+++ b/packages/db/src/impl/static/StaticDataLayerProvider.ts
@@ -138,7 +138,7 @@ export class StaticDataLayerProvider implements DataLayerProvider {
   }
 
   getCoursesDB(): CoursesDBInterface {
-    return new StaticCoursesDB(this.manifests);
+    return new StaticCoursesDB(this.manifests, this.dependencyNameToCourseId);
   }
 
   async getClassroomDB(
diff --git a/packages/db/src/impl/static/coursesDB.ts b/packages/db/src/impl/static/coursesDB.ts
index 6881713e1..25230d64a 100644
--- a/packages/db/src/impl/static/coursesDB.ts
+++ b/packages/db/src/impl/static/coursesDB.ts
@@ -6,10 +6,23 @@ import { StaticCourseManifest } from '../../util/packer/types';
 import { logger } from '../../util/logger';
 
 export class StaticCoursesDB implements CoursesDBInterface {
-  constructor(private manifests: Record<string, StaticCourseManifest>) {}
+  constructor(
+    private manifests: Record<string, StaticCourseManifest>,
+    private dependencyNameToCourseId?: Map<string, string>
+  ) {}
 
   async getCourseConfig(courseId: string): Promise<CourseConfig> {
-    const manifest = this.manifests[courseId];
+    // Try direct lookup by courseId first
+    let manifest = this.manifests[courseId];
+
+    // If not found, try lookup by dependency name (backwards compatibility)
+    if (!manifest && this.dependencyNameToCourseId) {
+      const mappedCourseId = this.dependencyNameToCourseId.get(courseId);
+      if (mappedCourseId) {
+        manifest = this.manifests[mappedCourseId];
+      }
+    }
+
     if (!manifest) {
       logger.warn(`Course manifest for ${courseId} not found`);
       throw new Error(`Course ${courseId} not found`);

From 80fc0e868e4b16aed19980c62cb355f0eb1829d5 Mon Sep 17 00:00:00 2001
From: NiloCK <colin@mrkennedy.ca>
Date: Wed, 12 Nov 2025 15:26:51 -0400
Subject: [PATCH 2/5] rm golang external test crs dep....

ID collision with local packed version caused problems
---
 docs/public/skuilder.json | 1 -
 1 file changed, 1 deletion(-)

diff --git a/docs/public/skuilder.json b/docs/public/skuilder.json
index 691974674..abe6213c4 100644
--- a/docs/public/skuilder.json
+++ b/docs/public/skuilder.json
@@ -4,7 +4,6 @@
   "description": "The root manifest for the vue-skuilder documentation site.",
   "dependencies": {
     "@skuilder/hero-course": "/vue-skuilder/static-courses/2aeb8315ef78f3e89ca386992d00825b/skuilder.json",
-    "@skuilder/external-test": "https://patched-network.github.io/demo-chess/static-courses/2aeb8315ef78f3e89ca386992d00825b/skuilder.json",
     "@skuilder/demo-chess": "https://patched-network.github.io/demo-chess/static-courses/demo-chess/skuilder.json"
   }
 }

From 392a518af1f86af784f735d6ccf1941ec23e1fff Mon Sep 17 00:00:00 2001
From: NiloCK <colin@mrkennedy.ca>
Date: Wed, 12 Nov 2025 15:27:25 -0400
Subject: [PATCH 3/5] rm working docs

---
 agent/BACKPORT_CHECKLIST.md | 273 --------------------------
 agent/a.1.assessment.md     | 210 --------------------
 agent/a.2.plan.md           | 379 ------------------------------------
 agent/a.3.todo.md           | 217 ---------------------
 4 files changed, 1079 deletions(-)
 delete mode 100644 agent/BACKPORT_CHECKLIST.md
 delete mode 100644 agent/a.1.assessment.md
 delete mode 100644 agent/a.2.plan.md
 delete mode 100644 agent/a.3.todo.md

diff --git a/agent/BACKPORT_CHECKLIST.md b/agent/BACKPORT_CHECKLIST.md
deleted file mode 100644
index 11f05fd9e..000000000
--- a/agent/BACKPORT_CHECKLIST.md
+++ /dev/null
@@ -1,273 +0,0 @@
-# Backport Checklist for Scaffolding Templates
-
-Changes tested in `/flutor` that need to be propagated to vue-skuilder template packages.
-
-**Note:** This document is self-contained. All necessary code examples and rationale are included below.
-
-## How to Use This Document
-
-1. **Copy this file** to the vue-skuilder monorepo for reference
-2. **Apply changes 1-6** to the template packages (standalone-ui, sk-contributor)
-3. **Test** using the testing checklist at the bottom
-4. **Ignore** the "Infrastructure Changes" section - those are already in the monorepo
-
-**Files to Update:**
-- `/packages/standalone-ui/vite.config.ts`
-- `/packages/standalone-ui/src/questions/index.ts`
-- `/packages/standalone-ui/src/main.ts`
-- `/packages/standalone-ui/src/questions/*QuestionView.vue` (all view components)
-- `/packages/sk-contributor/` (same files as above)
-- `/packages/standalone-ui/src/questions/README.md` (examples)
-
-## Context
-
-These fixes enable custom questions to work in both:
-- **Standalone mode** (`yarn dev`) - already worked
-- **Studio mode** (`yarn studio`) - now works after these fixes
-
-The root cause was a combination of:
-1. Browser unable to resolve bare imports in dynamically loaded modules
-2. Missing view component names for runtime lookup
-3. Side-effect import not running (views array staying empty)
-4. Incorrect views export format for studio-ui consumption
-
-## 1. Vite Config - External Dependencies & Terser
-**File:** `vite.config.ts`
-**Location:** Library build configuration
-**Change:**
-```typescript
-build: buildMode === 'library'
-  ? {
-      // ...
-      terserOptions: {
-        keep_classnames: true,
-        keep_fnames: true, // ADD: Preserve function names
-        mangle: {
-          properties: false, // ADD: Don't mangle static properties like seedData
-        },
-      },
-      rollupOptions: {
-        // CRITICAL: Do NOT externalize dependencies for studio mode
-        // Browser cannot resolve bare imports without import maps
-        external: [
-          // Leave empty - bundle everything for browser compatibility
-        ],
-      }
-    }
-```
-**Why:**
-- Terser options prevent minification from mangling static properties (seedData, views, dataShapes)
-- Empty externals array bundles all dependencies so browser can load the module without import maps
-- Previously tried externalizing to avoid duplication, but browser can't resolve `import { X } from "@vue-skuilder/courseware"` at runtime
-**Affects:**
-- `/packages/standalone-ui/vite.config.ts`
-- CLI template generation for new projects
-
----
-
-## 2. Question Index - Views Export Format
-**File:** `src/questions/index.ts`
-**Location:** `allCustomQuestions()` function
-**Change:**
-```typescript
-// OLD (broken):
-const views: ViewComponent[] = [];
-questionClasses.forEach((questionClass) => {
-  if (questionClass.views) {
-    questionClass.views.forEach((view) => {
-      views.push(view);
-    });
-  }
-});
-
-// NEW (working):
-const views: Array<{ name: string; component: ViewComponent }> = [];
-questionClasses.forEach((questionClass) => {
-  if (questionClass.views) {
-    questionClass.views.forEach((view) => {
-      const viewName = (view as any).name || (view as any).__name;
-      if (viewName) {
-        if (!views.find((existing) => existing.name === viewName)) {
-          views.push({ name: viewName, component: view });
-        }
-      } else {
-        console.warn('[allCustomQuestions] View component missing name property:', view);
-      }
-    });
-  }
-});
-```
-**Why:** Studio-ui expects `{ name, component }` format (see studio-ui/src/main.ts:183-189)
-**Affects:**
-- `/packages/standalone-ui/src/questions/index.ts`
-- `/packages/sk-contributor/src/questions/index.ts`
-
----
-
-## 3. Question Index - TypeScript Interface
-**File:** `src/questions/index.ts`
-**Location:** `CustomQuestionsExport` interface
-**Change:**
-```typescript
-export interface CustomQuestionsExport {
-  courses: CourseWare[];
-  questionClasses: Array<typeof Question>;
-  dataShapes: DataShape[];
-  views: Array<{ name: string; component: ViewComponent }>; // CHANGED from ViewComponent[]
-  inlineComponents: Record<string, any>;
-  meta: { /* ... */ };
-}
-```
-**Why:** Matches runtime format
-**Affects:**
-- `/packages/standalone-ui/src/questions/index.ts`
-- `/packages/sk-contributor/src/questions/index.ts`
-
----
-
-## 4. Main.ts - Import Questions Index
-**File:** `src/main.ts`
-**Location:** Before `allCourseWare.courses.push(exampleCourse)`
-**Change:**
-```typescript
-// Import allCourseWare singleton and exampleCourse
-import { allCourseWare } from '@vue-skuilder/courseware';
-// Import from index.ts to ensure view setup code runs
-import './questions/index'; // ADD THIS LINE
-import { exampleCourse } from './questions/exampleCourse';
-```
-**Why:** Ensures static view setup runs before course registration
-**Affects:**
-- `/packages/standalone-ui/src/main.ts`
-- `/packages/sk-contributor/src/main.ts`
-
----
-
-## 5. Question Class - Direct Inline Views
-**File:** `src/questions/MyQuestion.ts`
-**Location:** Question class static properties
-**Change:**
-```typescript
-// Import at top
-import { markRaw } from 'vue';
-import MyQuestionView from './MyQuestionView.vue';
-
-export class MyQuestion extends Question {
-  public static dataShapes = [/* ... */];
-
-  // Direct inline registration - no external setup needed
-  public static views = [markRaw(MyQuestionView)]; // CHANGED from empty array
-
-  // ...
-}
-```
-**Why:** Self-contained, works immediately, no fragile side-effects
-**Affects:**
-- Template examples in `/packages/standalone-ui/src/questions/README.md`
-- Template examples in `/packages/sk-contributor/src/questions/README.md`
-- Existing template questions (NumberRangeQuestion, etc.)
-
----
-
-## 6. Vue Component - DefineOptions Name
-**File:** `src/questions/MyQuestionView.vue`
-**Location:** Script setup
-**Change:**
-```typescript
-<script setup lang="ts">
-import { defineOptions } from 'vue'; // ADD import
-
-defineOptions({
-  name: 'MyQuestionView' // ADD this block
-});
-
-// rest of setup...
-```
-**Why:** Vue components need explicit names for runtime lookup
-**Affects:**
-- All template Vue view components
-- README examples
-
----
-
-## 7. Remove Index.ts Side-Effects (Future)
-**File:** `src/questions/index.ts`
-**Location:** Top-level code
-**Change:**
-```typescript
-// REMOVE these lines (views should be set in question files directly):
-// import SustainedNoteQuestionView from './SustainedNoteQuestionView.vue';
-// SustainedNoteQuestion.views = [markRaw(SustainedNoteQuestionView)];
-```
-**Why:** Side-effects are fragile; prefer direct inline registration
-**Status:** Deferred until all templates use Pattern 1
-**Affects:**
-- `/packages/standalone-ui/src/questions/index.ts`
-
----
-
-## Implementation Priority
-
-### Phase 1 (Critical - Breaks studio mode)
-- [ ] #2: Fix views export format in index.ts
-- [ ] #3: Update TypeScript interface
-- [ ] #1: Add terser options to vite.config
-
-### Phase 2 (Important - Breaks runtime)
-- [ ] #4: Add index.ts import to main.ts
-- [ ] #6: Add defineOptions to all template Vue components
-
-### Phase 3 (Nice to have)
-- [ ] #5: Update documentation/examples to show direct inline pattern
-- [ ] #7: Remove side-effects from index.ts (future)
-
-## Testing Checklist
-
-After backporting, verify:
-- [ ] `yarn dev` works (standalone mode)
-- [ ] `yarn studio` works (studio mode)
-- [ ] Custom questions appear in studio CreateCardView
-- [ ] Card creation works with custom DataShapes
-- [ ] Seed data registration doesn't error
-- [ ] Cards render correctly in both modes
-- [ ] Custom inline markdown components work
-
-## Infrastructure Changes (Already Done in Monorepo)
-
-**⚠️ You do NOT need to apply these changes - they are already in the monorepo codebase.**
-
-These were supporting infrastructure fixes made alongside the template changes:
-
-### CLI - studio.ts
-**File:** `/packages/cli/src/commands/studio.ts`
-**What changed:** Config import path updated when copying to dist
-```typescript
-// Line ~1147
-configContent.importPath = '/assets/questions.mjs'; // Absolute path from root
-```
-**Why:** Ensures browser can find the bundled questions module
-
-### Studio-UI - main.ts
-**File:** `/packages/studio-ui/src/main.ts`
-**What changed:**
-- Registers custom courses with `allCourseWare.courses.push(...customQuestions.courses)`
-- Added verbose debug logging for troubleshooting
-- Uses `/* @vite-ignore */` comment for dynamic import
-
-**Why:** Studio-ui now properly integrates custom courses into the singleton
-
----
-
-## Related Files
-
-**Templates:**
-- `/packages/standalone-ui/src/questions/`
-- `/packages/sk-contributor/src/questions/`
-
-**CLI Generation:**
-- `/packages/cli/src/utils/template.ts` (may need updates)
-- `/packages/cli/src/commands/scaffold.ts`
-
-**Documentation:**
-- `/packages/standalone-ui/src/questions/README.md`
-- Main docs site (if applicable)
diff --git a/agent/a.1.assessment.md b/agent/a.1.assessment.md
deleted file mode 100644
index 73a5f9a64..000000000
--- a/agent/a.1.assessment.md
+++ /dev/null
@@ -1,210 +0,0 @@
-# Assessment: Backport Custom Questions Fixes
-
-## Context
-
-The `BACKPORT_CHECKLIST.md` document details 7 changes that were tested in `/flutor` to enable custom questions to work in both standalone mode (`yarn dev`) and studio mode (`yarn studio`). These fixes address:
-
-1. Browser unable to resolve bare imports in dynamically loaded modules
-2. Missing view component names for runtime lookup
-3. Side-effect import not running (views array staying empty)
-4. Incorrect views export format for studio-ui consumption
-
-## Current State Analysis
-
-Branch: `custom-q-packing-updates` (fresh, no commits yet)
-
-### What's Already Fixed
-
-**Partially Fixed:**
-- ✅ Vite config: Empty externals array (bundling everything for browser compatibility)
-- ✅ Vite config: `keep_classnames: true` in terser options
-- ✅ Question classes: Already using `{ name, component }` format in static views
-  - `SimpleTextQuestion.views = [{ name: 'SimpleTextQuestionView', component: SimpleTextQuestionView }]`
-  - Same for MultipleChoiceQuestion and NumberRangeQuestion
-
-### What's Missing
-
-**Critical Issues (Phase 1):**
-1. ❌ **Vite config terser options incomplete**
-   - Missing: `keep_fnames: true`
-   - Missing: `mangle: { properties: false }`
-   - Affects: `/packages/standalone-ui/vite.config.ts` (line 48-50)
-   - Affects: `/packages/sk-contributor/vite.config.ts` (line 63-65)
-
-2. ❌ **Views export format in index.ts**
-   - Current: `const views: ViewComponent[] = []` (line 55)
-   - Expected: `const views: Array<{ name: string; component: ViewComponent }> = []`
-   - Missing name extraction logic with warnings
-   - Affects: Both packages' `src/questions/index.ts`
-
-3. ❌ **TypeScript interface mismatch**
-   - Current: `views: ViewComponent[]` (line 105)
-   - Expected: `views: Array<{ name: string; component: ViewComponent }>`
-   - Affects: `CustomQuestionsExport` interface in both `index.ts` files
-
-**Important Issues (Phase 2):**
-4. ❌ **Side-effect import missing in main.ts**
-   - Neither main.ts imports `'./questions/index'` before exampleCourse
-   - Current: Line 28 directly imports exampleCourse
-   - Expected: Add `import './questions/index';` before line 28
-   - Affects: `/packages/standalone-ui/src/main.ts`
-   - Affects: `/packages/sk-contributor/src/main.ts`
-
-5. ❌ **Vue components missing defineOptions**
-   - None of the Vue components have `defineOptions({ name: '...' })`
-   - Required for runtime component lookup
-   - Affects: All 3 view components in both packages:
-     - SimpleTextQuestionView.vue
-     - MultipleChoiceQuestionView.vue
-     - NumberRangeQuestionView.vue
-
-**Documentation (Phase 3):**
-6. ❌ **README examples outdated**
-   - Current README shows old patterns
-   - Should document direct inline registration pattern
-   - Affects: `/packages/standalone-ui/src/questions/README.md`
-
-## Risk Assessment
-
-### If We Don't Apply These Changes
-
-**Studio mode will likely break:**
-- Custom questions won't appear in studio CreateCardView
-- Card creation with custom DataShapes may fail
-- View components may not be found at runtime
-- Minification may mangle static properties (seedData, views, dataShapes)
-
-**Standalone mode may work:**
-- Direct imports in main.ts already register course
-- No dynamic module loading required
-- But builds may still have mangled properties
-
-### If We Apply Changes Incorrectly
-
-**Low risk areas:**
-- Terser options (additive, won't break existing code)
-- Vue defineOptions (additive, standard Vue 3 pattern)
-- TypeScript interface updates (compile-time only)
-
-**Medium risk areas:**
-- Views export format change (runtime behavior change)
-  - Studio-ui expects `{ name, component }` format
-  - If we break this, studio mode will definitely fail
-  - But standalone mode doesn't use this export currently
-
-**High risk areas:**
-- Side-effect import ordering
-  - If views array setup runs too early/late, may cause registration issues
-  - But since question classes already have inline views, this is less critical
-
-## Options
-
-### Option 1: Full Sequential Backport
-Apply all 6 changes in the priority order from the checklist:
-- Phase 1: Changes 1-3 (vite config, views export, interface)
-- Phase 2: Changes 4-5 (side-effect import, defineOptions)
-- Phase 3: Change 6 (documentation)
-
-**Pros:**
-- Complete implementation matching tested flutor state
-- Follows documented priority order
-- Clear testing checkpoints between phases
-
-**Cons:**
-- More changes than strictly necessary
-- Includes defensive fixes for problems we may not have
-
-### Option 2: Minimal Critical Path
-Apply only the changes that directly affect studio mode:
-1. Terser options (keep_fnames, mangle.properties)
-2. Views export format + name extraction
-3. TypeScript interface update
-4. Vue defineOptions in all components
-
-Skip:
-- Side-effect import (since classes already have inline views)
-- Documentation (do in separate PR)
-
-**Pros:**
-- Minimum necessary changes
-- Faster to implement and test
-- Lower risk of unintended side effects
-
-**Cons:**
-- May still have latent issues with view registration
-- Documentation stays out of sync
-
-### Option 3: Investigate Before Backporting
-First test current state to identify actual failures:
-1. Build library mode for both packages
-2. Test studio mode integration
-3. Only apply fixes for confirmed failures
-
-**Pros:**
-- Evidence-based approach
-- Don't fix what isn't broken
-- Better understanding of actual issues
-
-**Cons:**
-- Requires studio-ui setup and testing infrastructure
-- May waste time if multiple test cycles needed
-- Checklist authors already did this investigation
-
-### Option 4: Full Backport with Verification
-Apply all changes but verify each phase:
-1. Apply Phase 1, build, verify no breaks
-2. Apply Phase 2, build, verify no breaks
-3. Apply Phase 3 (docs only)
-4. Test both standalone and studio modes
-
-**Pros:**
-- High confidence in final state
-- Methodical with verification points
-- Documents any deviations from checklist
-
-**Cons:**
-- Time intensive
-- Requires studio mode test setup
-
-## Recommendation
-
-**Option 2: Minimal Critical Path** with selective additions
-
-Apply these specific changes:
-
-**Immediate (Critical):**
-1. ✅ Vite config terser options - Add `keep_fnames` and `mangle.properties`
-2. ✅ Views export format - Change to `{ name, component }[]` with name extraction
-3. ✅ TypeScript interface - Update to match runtime format
-4. ✅ Vue defineOptions - Add to all 6 view components (3 per package)
-
-**Deferred (Safe to skip for now):**
-5. ⏸️ Side-effect import - Skip because classes already have inline views
-6. ⏸️ Documentation updates - Do in separate documentation PR
-
-**Rationale:**
-- Question classes already use correct inline pattern, so side-effect import is redundant
-- The checklist itself notes change #7 (removing side-effects) should be "future" work
-- This gets us to a working state faster with less risk
-- We can add the side-effect import later if we discover view registration issues
-
-**Success Criteria:**
-After applying changes:
-- ✅ Library builds succeed for both packages
-- ✅ No minification of static properties (seedData, views, dataShapes)
-- ✅ View components have explicit names for runtime lookup
-- ✅ Studio-ui can import and parse the views array correctly
-
-**Testing Plan:**
-1. Apply changes to standalone-ui first
-2. Build library mode: `BUILD_MODE=library yarn workspace @vue-skuilder/standalone-ui build`
-3. Verify output in `dist-lib/` has correct structure
-4. Replicate to sk-contributor
-5. Test integration with studio mode (if available)
-
-## Next Steps
-
-If approved, I will:
-1. Create `a.2.plan.md` detailing the specific changes
-2. Create `a.3.todo.md` with checklist of files to modify
-3. Proceed with implementation in phases
diff --git a/agent/a.2.plan.md b/agent/a.2.plan.md
deleted file mode 100644
index 2c240a9cd..000000000
--- a/agent/a.2.plan.md
+++ /dev/null
@@ -1,379 +0,0 @@
-# Plan: Backport Custom Questions Fixes with CI Verification
-
-## Objective
-
-Apply all custom questions fixes from the flutor testing to the monorepo templates, and add CI tests to prevent regression.
-
-## Success Criteria
-
-1. ✅ All 6 backport changes applied to both `standalone-ui` and `sk-contributor`
-2. ✅ Library builds succeed with correct output structure
-3. ✅ Standalone mode works (existing test already covers this)
-4. ✅ Studio mode works (new test to verify)
-5. ✅ CI catches breakage if any of these changes regress
-
-## Scope
-
-### In Scope
-- All changes from BACKPORT_CHECKLIST phases 1-3
-- Both template packages: standalone-ui and sk-contributor
-- CI enhancements to test custom questions
-- Studio mode verification test
-
-### Out of Scope
-- Changes to infrastructure packages (already done per checklist)
-- Platform-ui changes (not a scaffolding template)
-- Breaking API changes to Question class
-
-## Implementation Phases
-
-### Phase 1: Backport Critical Changes (Both Packages)
-
-**Files to modify:**
-- `packages/standalone-ui/vite.config.ts`
-- `packages/sk-contributor/vite.config.ts`
-- `packages/standalone-ui/src/questions/index.ts`
-- `packages/sk-contributor/src/questions/index.ts`
-
-**Changes:**
-
-1. **Vite config terser options** (BACKPORT #1)
-   ```typescript
-   terserOptions: {
-     keep_classnames: true,
-     keep_fnames: true,              // ADD
-     mangle: {
-       properties: false,            // ADD
-     },
-   }
-   ```
-
-2. **Views export format** (BACKPORT #2)
-   ```typescript
-   // Change from:
-   const views: ViewComponent[] = [];
-
-   // To:
-   const views: Array<{ name: string; component: ViewComponent }> = [];
-
-   // With name extraction logic:
-   questionClass.views.forEach((view) => {
-     const viewName = (view as any).name || (view as any).__name;
-     if (viewName) {
-       if (!views.find((existing) => existing.name === viewName)) {
-         views.push({ name: viewName, component: view });
-       }
-     } else {
-       console.warn('[allCustomQuestions] View component missing name property:', view);
-     }
-   });
-   ```
-
-3. **TypeScript interface** (BACKPORT #3)
-   ```typescript
-   export interface CustomQuestionsExport {
-     // ... other fields
-     views: Array<{ name: string; component: ViewComponent }>;  // CHANGE
-   }
-   ```
-
-### Phase 2: Add Component Names (Both Packages)
-
-**Files to modify:**
-- `packages/standalone-ui/src/questions/SimpleTextQuestionView.vue`
-- `packages/standalone-ui/src/questions/MultipleChoiceQuestionView.vue`
-- `packages/standalone-ui/src/questions/NumberRangeQuestionView.vue`
-- `packages/sk-contributor/src/questions/SimpleTextQuestionView.vue`
-- `packages/sk-contributor/src/questions/MultipleChoiceQuestionView.vue`
-- `packages/sk-contributor/src/questions/NumberRangeQuestionView.vue`
-
-**Changes:** (BACKPORT #6)
-```vue
-<script setup lang="ts">
-import { defineOptions } from 'vue';  // ADD if not present
-
-defineOptions({
-  name: 'SimpleTextQuestionView'  // ADD - use appropriate name for each
-});
-
-// rest of setup...
-```
-
-### Phase 3: Add Side-Effect Import (Both Packages)
-
-**Files to modify:**
-- `packages/standalone-ui/src/main.ts`
-- `packages/sk-contributor/src/main.ts`
-
-**Changes:** (BACKPORT #4)
-```typescript
-// Import allCourseWare singleton and exampleCourse
-import { allCourseWare } from '@vue-skuilder/courseware';
-import './questions/index';  // ADD THIS LINE
-import { exampleCourse } from './questions/exampleCourse';
-```
-
-**Rationale:** Even though question classes have inline views, this ensures the index.ts module runs and all exports are properly initialized before course registration.
-
-### Phase 4: Update Documentation
-
-**Files to modify:**
-- `packages/standalone-ui/src/questions/README.md`
-- `packages/sk-contributor/src/questions/README.md` (if exists)
-
-**Changes:** (BACKPORT #5)
-Update examples to show:
-- Direct inline view registration pattern
-- Use of `markRaw()` for Vue components
-- Use of `defineOptions({ name: '...' })` in Vue components
-- Correct `{ name, component }` format in static views
-
-### Phase 5: Build and Verify
-
-**Steps:**
-1. Build standalone-ui library mode
-   ```bash
-   BUILD_MODE=library yarn workspace @vue-skuilder/standalone-ui build
-   ```
-
-2. Verify output in `packages/standalone-ui/dist-lib/`:
-   - `questions.mjs` exists
-   - Static properties not mangled (inspect with `less questions.mjs`)
-   - Views array has correct structure
-
-3. Build sk-contributor library mode
-   ```bash
-   BUILD_MODE=library yarn workspace @vue-skuilder/sk-contributor build
-   ```
-
-4. Verify output in `packages/sk-contributor/dist-lib/`
-
-5. Test standalone dev mode
-   ```bash
-   yarn workspace @vue-skuilder/standalone-ui dev
-   # Navigate to /study and verify cards render
-   ```
-
-## CI Enhancement Plan
-
-### Current State
-- `ci-pkg-cli.yml` tests scaffolded apps
-- Runs `yarn try:init` to create test project
-- Runs basic smoke test (home page loads, study view renders cards)
-
-### Proposed Enhancements
-
-#### 1. Enhanced Scaffolded App Test
-
-**Extend:** `packages/cli/cypress/e2e/scaffolded-app.cy.js`
-
-**Add tests for:**
-```javascript
-describe('Custom Questions - Standalone Mode', () => {
-  it('should render custom question types in study view', () => {
-    cy.visit('/study');
-
-    // Verify SimpleTextQuestionView renders
-    // (component should have data-viewable="SimpleTextQuestionView")
-    cy.get('[data-viewable*="SimpleTextQuestionView"]', { timeout: 15000 })
-      .should('exist');
-
-    // Verify question has input field
-    cy.get('input[placeholder*="answer"], input[type="text"]')
-      .should('be.visible');
-  });
-
-  it('should have custom data shapes in example course', () => {
-    // This verifies that dataShapes are properly exported
-    // Could check via dev tools or API if exposed
-  });
-});
-```
-
-#### 2. Studio Mode Test (New)
-
-**New file:** `packages/cli/cypress/e2e/scaffolded-app-studio.cy.js`
-
-**Test studio mode integration:**
-```javascript
-describe('Custom Questions - Studio Mode', () => {
-  before(() => {
-    // Start studio mode server
-    // This may require adding a studio start script to testproject
-  });
-
-  it('should load studio UI with custom questions', () => {
-    cy.visit('http://localhost:6174'); // or wherever studio runs
-
-    // Verify studio UI loads
-    cy.get('body').should('be.visible');
-  });
-
-  it('should show custom data shapes in CreateCardView', () => {
-    cy.visit('http://localhost:6174/create');
-
-    // Verify custom DataShapes appear in dropdown/selector
-    cy.contains('SimpleTextQuestion').should('exist');
-    cy.contains('MultipleChoiceQuestion').should('exist');
-    cy.contains('NumberRangeQuestion').should('exist');
-  });
-
-  it('should render custom views when creating card', () => {
-    cy.visit('http://localhost:6174/create');
-
-    // Select custom question type
-    cy.contains('SimpleTextQuestion').click();
-
-    // Verify view component loads (may need to fill required fields first)
-    // Check for component-specific elements
-  });
-});
-```
-
-#### 3. CI Workflow Enhancement
-
-**Modify:** `.github/workflows/ci-pkg-cli.yml`
-
-**Add studio mode test step:**
-```yaml
-- name: Start studio mode and wait
-  working-directory: packages/cli/testproject
-  run: |
-    # Start studio server in background
-    npm run studio &
-    # Wait for studio to be ready
-    npx wait-on http://localhost:6174 --timeout 60000
-
-- name: Run E2E tests on studio mode
-  working-directory: packages/cli
-  run: yarn test:e2e:studio:headless
-
-- name: Cleanup services
-  if: always()
-  run: |
-    kill $(lsof -t -i:5173) || true
-    kill $(lsof -t -i:6174) || true  # ADD studio port
-    yarn couchdb:stop
-```
-
-**Add to cleanup step:**
-```yaml
-- name: Cleanup services
-  if: always()
-  run: |
-    # Clean up dev server
-    kill $(lsof -t -i:5173) || true
-    # Clean up studio server
-    kill $(lsof -t -i:6174) || true
-    # Clean up CouchDB
-    yarn couchdb:stop
-```
-
-#### 4. Package Scripts
-
-**Add to:** `packages/cli/package.json`
-```json
-{
-  "scripts": {
-    "test:e2e:studio": "cypress open --config-file cypress.studio.config.js",
-    "test:e2e:studio:headless": "cypress run --config-file cypress.studio.config.js"
-  }
-}
-```
-
-**Create:** `packages/cli/cypress.studio.config.js`
-```javascript
-const { defineConfig } = require('cypress');
-
-module.exports = defineConfig({
-  e2e: {
-    baseUrl: 'http://localhost:6174',
-    specPattern: 'cypress/e2e/*-studio.cy.js',
-    supportFile: 'cypress/support/e2e.js',
-  },
-});
-```
-
-## Verification Checklist
-
-After completing all phases:
-
-**Manual Verification:**
-- [ ] `yarn dev` works (standalone mode) - both packages
-- [ ] `yarn studio` works (studio mode) - both packages
-- [ ] Custom questions appear in studio CreateCardView
-- [ ] Card creation works with custom DataShapes
-- [ ] Seed data registration doesn't error
-- [ ] Cards render correctly in both modes
-- [ ] Custom inline markdown components work (if applicable)
-
-**Build Verification:**
-- [ ] Library build completes without errors
-- [ ] Output has `questions.mjs` with correct structure
-- [ ] Static properties preserved (not mangled)
-- [ ] Views array has `{ name, component }` format
-
-**CI Verification:**
-- [ ] All existing CI tests pass
-- [ ] New custom questions tests pass
-- [ ] Studio mode tests pass (if added)
-- [ ] No console errors in test runs
-
-## Risks and Mitigations
-
-### Risk: Studio mode test complexity
-Studio mode may require more complex setup (database, auth, etc.)
-
-**Mitigation:**
-- Start with basic "does it load" test
-- Gradually add more specific tests
-- Document studio setup requirements
-
-### Risk: CI instability with multiple servers
-Running dev + studio + couchdb may cause port conflicts or timing issues
-
-**Mitigation:**
-- Use explicit port assignments
-- Add robust wait-on checks
-- Ensure cleanup runs even on failure
-- Consider separate CI jobs for studio tests
-
-### Risk: Breaking changes to question API
-Changes to views format might break existing user code
-
-**Mitigation:**
-- These are template packages, not library code
-- Changes only affect scaffolded projects going forward
-- Document migration path in README
-- Consider adding migration guide to docs site
-
-### Risk: Test maintenance burden
-More tests = more maintenance
-
-**Mitigation:**
-- Keep tests focused on critical paths
-- Use test selectors that are stable
-- Document test rationale in comments
-- Review test failures promptly
-
-## Timeline Estimate
-
-- **Phase 1-3 (Backport):** 1-2 hours
-- **Phase 4 (Documentation):** 30 minutes
-- **Phase 5 (Build verification):** 30 minutes
-- **CI Enhancement:** 2-3 hours
-  - Writing tests: 1-2 hours
-  - CI setup: 1 hour
-  - Debugging: variable
-
-**Total:** 4-6 hours
-
-## Next Steps
-
-1. Get approval on this plan
-2. Create detailed todo checklist
-3. Start with Phase 1 on standalone-ui
-4. Verify each phase before moving to next
-5. Replicate to sk-contributor
-6. Add CI enhancements
-7. Document any deviations or learnings
diff --git a/agent/a.3.todo.md b/agent/a.3.todo.md
deleted file mode 100644
index 9f81b5940..000000000
--- a/agent/a.3.todo.md
+++ /dev/null
@@ -1,217 +0,0 @@
-# Todo: Backport Custom Questions Fixes with CI Verification
-
-## Phase 1: Backport Critical Changes to standalone-ui
-
-### 1.1 Vite Config - Terser Options
-- [x] Open `packages/standalone-ui/vite.config.ts`
-- [x] Locate `terserOptions` in library build config (around line 48-50)
-- [x] Add `keep_fnames: true`
-- [x] Add `mangle: { properties: false }`
-- [x] Verify syntax is correct
-- [x] Sync same changes to `packages/cli/src/utils/template.ts` (line ~193)
-  - **Why:** CLI uses template.ts to generate vite.config.ts for scaffolded projects
-  - **CI Check:** Automated check ensures these stay in sync
-
-### 1.2 Views Export Format - index.ts
-- [x] Open `packages/standalone-ui/src/questions/index.ts`
-- [x] Change line 55: `const views: ViewComponent[]` to `const views: Array<{ name: string; component: ViewComponent }>`
-- [x] Replace views collection logic (lines 56-65) with name extraction pattern:
-  ```typescript
-  questionClass.views.forEach((view) => {
-    const viewName = (view as any).name || (view as any).__name;
-    if (viewName) {
-      if (!views.find((existing) => existing.name === viewName)) {
-        views.push({ name: viewName, component: view });
-      }
-    } else {
-      console.warn('[allCustomQuestions] View component missing name property:', view);
-    }
-  });
-  ```
-
-### 1.3 TypeScript Interface - index.ts
-- [x] In same file, locate `CustomQuestionsExport` interface (line 99-114)
-- [x] Change line 105: `views: ViewComponent[]` to `views: Array<{ name: string; component: ViewComponent }>`
-
-### 1.4 Test Build (DEFERRED)
-- [ ] Run: `BUILD_MODE=library yarn workspace @vue-skuilder/standalone-ui build`
-- [ ] Verify build succeeds
-- [ ] Inspect `packages/standalone-ui/dist-lib/questions.mjs` for correct output
-
-## Phase 2: Add Component Names to standalone-ui
-
-### 2.1 SimpleTextQuestionView.vue
-- [x] Open `packages/standalone-ui/src/questions/SimpleTextQuestionView.vue`
-- [x] Add import if not present: `import { defineOptions } from 'vue';`
-- [x] Add after imports (before props):
-  ```typescript
-  defineOptions({
-    name: 'SimpleTextQuestionView'
-  });
-  ```
-
-### 2.2 MultipleChoiceQuestionView.vue
-- [x] Open `packages/standalone-ui/src/questions/MultipleChoiceQuestionView.vue`
-- [x] Add defineOptions import
-- [x] Add: `defineOptions({ name: 'MultipleChoiceQuestionView' });`
-
-### 2.3 NumberRangeQuestionView.vue
-- [x] Open `packages/standalone-ui/src/questions/NumberRangeQuestionView.vue`
-- [x] Add defineOptions import
-- [x] Add: `defineOptions({ name: 'NumberRangeQuestionView' });`
-
-### 2.4 Test Build Again (DEFERRED)
-- [ ] Run: `BUILD_MODE=library yarn workspace @vue-skuilder/standalone-ui build`
-- [ ] Verify build succeeds
-- [ ] Check that component names are preserved in output
-
-## Phase 3: Side-Effect Import to standalone-ui (OMITTED)
-
-**DECISION:** This phase was omitted because the side-effect import is not needed.
-
-**Rationale:**
-- Question classes already have inline view registration (e.g., `SimpleTextQuestion.views = [{ name, component }]`)
-- No additional setup code exists in `index.ts` that needs to run
-- BACKPORT_CHECKLIST #7 even recommends removing side-effects as "future" work
-- We're already using the preferred direct inline pattern (#5)
-
-**Risk:** If tests fail with "view not found" errors, we may need to add this back. But current analysis indicates it's redundant.
-
-### 3.1 Main.ts Import
-- [x] ~~Add `import './questions/index';`~~ OMITTED (not needed)
-
-### 3.2 Test Dev Mode (DEFERRED)
-- [ ] Run: `yarn workspace @vue-skuilder/standalone-ui dev`
-- [ ] Navigate to http://localhost:6173
-- [ ] Verify app loads without errors
-- [ ] Check browser console for warnings
-
-## Phase 4: sk-contributor Package (REMOVED)
-
-**DECISION:** The sk-contributor package never made it off the ground and is being removed from the monorepo.
-
-### 4.1 Remove Package
-- [ ] User will execute: `git rm -r packages/sk-contributor`
-- [ ] Update workspace references if needed (package.json, tsconfig, etc.)
-
-**Note:** All backport changes were only applied to standalone-ui. If sk-contributor is revived in the future, it would need the same changes applied.
-
-## Phase 5: Update Documentation
-
-### 5.1 Standalone-ui README
-- [x] Open `packages/standalone-ui/src/questions/README.md`
-- [x] Update examples to show `defineOptions({ name: '...' })` pattern
-- [x] Update examples to show direct inline view registration with `markRaw()`
-- [x] Add note about `markRaw()` for Vue components
-- [x] Add note about `{ name, component }` format for studio compatibility
-- [x] Note that side-effect import is NOT needed (inline pattern preferred)
-- [x] Add "Best Practices" section with key guidelines
-
-## Phase 6: CI Enhancement - Custom Questions Workflow Test
-
-**Strategy:** Create end-to-end test of custom questions workflow:
-1. Scaffold empty static course
-2. Start studio mode
-3. Create card using custom DataShape via Cypress
-4. Verify card renders in studio browse view
-5. Flush to static via Cypress button click
-6. Start dev mode
-7. Verify card renders in dev study view
-
-**Key Decisions:**
-- Leave existing `scaffolded-app.cy.js` alone (tests packed courses)
-- New script: `try:init:empty` (no --import-course-data)
-- **TWO Cypress test files** (studio tests, then dev tests - cleaner CI workflow)
-- Clean up between existing and new test
-- Studio mode manages its own CouchDB (no conflicts)
-- Flush via Cypress clicking studio UI button
-
-### 6.1 CLI Script - Empty Project Init
-- [x] Add to `packages/cli/package.json`:
-  - `try:init:empty` - scaffolds empty project with template custom questions
-  - Includes npm install and file:.. dependencies
-
-### 6.2 Cypress Tests - Custom Questions Workflow
-- [x] Create `packages/cli/cypress/e2e/custom-questions-studio.cy.js`
-  - Test 1: Studio UI loads
-  - Test 2: Custom DataShapes appear in CreateCardView
-  - Test 3: Create card with SimpleTextQuestion
-  - Test 4: Card renders in studio browse view
-  - Test 5: Flush to static button works
-- [x] Create `packages/cli/cypress/e2e/custom-questions-dev.cy.js`
-  - Test 1: Dev mode loads
-  - Test 2: Flushed card renders in study view
-  - Test 3: Can interact with custom question
-
-### 6.3 CI Workflow Updates
-- [x] Update `.github/workflows/ci-pkg-cli.yml`
-- [x] Add after existing test cleanup:
-  - Create empty project
-  - Start studio mode (wait on 7174)
-  - Run studio tests
-  - Shutdown studio
-  - Start dev mode (wait on 6173)
-  - Run dev tests
-  - Final cleanup (all ports)
-
-### 6.4 Package Scripts
-- [x] Update existing scripts to be specific:
-  - `test:e2e` - now targets only `scaffolded-app.cy.js`
-  - `test:e2e:headless` - now targets only `scaffolded-app.cy.js`
-- [x] Add new custom questions scripts:
-  - `test:e2e:custom:studio` - open studio tests
-  - `test:e2e:custom:studio:headless` - run studio tests
-  - `test:e2e:custom:dev` - open dev tests
-  - `test:e2e:custom:dev:headless` - run dev tests
-
-### 6.5 Local Testing (DEFERRED)
-- [ ] Build CLI: `yarn workspace @vue-skuilder/cli build`
-- [ ] Run empty init: `cd packages/cli && yarn try:init:empty`
-- [ ] Test studio: `cd testproject-empty && npx skuilder studio`
-- [ ] Manually verify custom questions appear in CreateCardView
-- [ ] Run Cypress studio tests: `cd packages/cli && yarn test:e2e:custom:studio`
-- [ ] After flush, run dev tests: `yarn test:e2e:custom:dev`
-
-## Phase 7: Obsolete (Merged into Phase 6)
-
-Studio mode tests are now fully covered in Phase 6 with the two-file Cypress approach:
-- `custom-questions-studio.cy.js` tests studio mode functionality
-- `custom-questions-dev.cy.js` tests dev mode after flush
-- CI workflow runs both sequentially with proper server lifecycle management
-
-## Phase 8: Final Verification
-
-### 8.1 Manual Testing
-- [ ] Test standalone-ui dev mode: `yarn workspace @vue-skuilder/standalone-ui dev`
-- [ ] Navigate to /study and verify cards render
-- [ ] Test sk-contributor dev mode (if applicable)
-- [ ] From testproject: Run `npx skuilder studio`
-- [ ] Verify studio loads
-- [ ] Check CreateCardView for custom question types
-
-### 8.2 Build Verification
-- [ ] Run full monorepo build: `yarn build`
-- [ ] Verify no errors
-- [ ] Check both library outputs exist:
-  - `packages/standalone-ui/dist-lib/questions.mjs`
-  - `packages/sk-contributor/dist-lib/questions.mjs`
-
-### 8.3 CI Verification
-- [ ] Push branch
-- [ ] Monitor CI run for `ci-pkg-cli.yml`
-- [ ] Check all tests pass
-- [ ] Review any failures and iterate
-
-### 8.4 Documentation
-- [ ] Create summary of changes in `agent/a.4.completion.md`
-- [ ] Note any deviations from plan
-- [ ] List any discovered issues or future work
-- [ ] Update BACKPORT_CHECKLIST.md status if needed
-
-## Notes
-
-- **Phase 7 (Studio CI)** is marked optional - can be deferred to separate PR if complex
-- Test locally before pushing to CI
-- Keep commits atomic per phase for easier rollback
-- Monitor console output for warnings about missing view names
-- If studio tests prove too complex, document as future work

From a252f993f0974346fcb02c30591f9eb556301ada Mon Sep 17 00:00:00 2001
From: NiloCK <colin@mrkennedy.ca>
Date: Wed, 12 Nov 2025 22:55:49 -0400
Subject: [PATCH 4/5] add docs datalayer sanity check to CI...

---
 .github/workflows/docs-deploy.yml |  32 +++-
 cypress.config.ts                 |  11 ++
 docs/test/embedded-course.cy.ts   | 114 ++++++++++++++
 package.json                      |   8 +-
 tsconfig.json                     |  16 ++
 yarn.lock                         | 251 +++++++++++++++++++++++++++++-
 6 files changed, 423 insertions(+), 9 deletions(-)
 create mode 100644 cypress.config.ts
 create mode 100644 docs/test/embedded-course.cy.ts
 create mode 100644 tsconfig.json

diff --git a/.github/workflows/docs-deploy.yml b/.github/workflows/docs-deploy.yml
index 7e6df6a40..3601a99d2 100644
--- a/.github/workflows/docs-deploy.yml
+++ b/.github/workflows/docs-deploy.yml
@@ -47,17 +47,37 @@ jobs:
         run: yarn build:lib
       - name: Build with VitePress
         run: yarn docs:build # or pnpm docs:build / yarn docs:build / bun run docs:build
-      - name: Upload artifact
-        uses: actions/upload-pages-artifact@v3
-        with:
-          path: docs/.vitepress/dist
-
+   
+  # Test Job
+  test:
+    name: Test
+    runs-on: ubuntu-latest
+    steps:
+       - name: Checkout
+         uses: actions/checkout@v4
+       - name: Setup Node
+         uses: actions/setup-node@v4
+         with:
+           node-version: 22
+           cache: yarn
+       - name: Install dependencies
+         run: yarn install
+       - name: Build skuilder libraries
+         run: yarn build:lib
+       - name: Start dev server and run tests
+         run: |
+           yarn docs:dev &
+           SERVER_PID=$!
+           npx wait-on http://localhost:5173/vue-skuilder
+           yarn docs:test
+           kill $SERVER_PID
+       
   # Deployment job
   deploy:
     environment:
       name: github-pages
       url: ${{ steps.deployment.outputs.page_url }}
-    needs: build
+    needs: [build, test]
     runs-on: ubuntu-latest
     name: Deploy
     steps:
diff --git a/cypress.config.ts b/cypress.config.ts
new file mode 100644
index 000000000..e5a64069e
--- /dev/null
+++ b/cypress.config.ts
@@ -0,0 +1,11 @@
+import { defineConfig } from 'cypress';
+
+export default defineConfig({
+  e2e: {
+    baseUrl: 'http://localhost:5173',
+    supportFile: false,
+    specPattern: 'docs/test/**/*.cy.{js,jsx,ts,tsx}',
+    video: false,
+    screenshotOnRunFailure: true,
+  },
+});
diff --git a/docs/test/embedded-course.cy.ts b/docs/test/embedded-course.cy.ts
new file mode 100644
index 000000000..d47586d45
--- /dev/null
+++ b/docs/test/embedded-course.cy.ts
@@ -0,0 +1,114 @@
+/**
+ * Smoke test for docs site embedded course functionality
+ *
+ * Ensures that:
+ * - The embedded course loads without "not found" errors
+ * - The data layer initializes correctly
+ * - Study sessions can be started
+ * - Cards load successfully
+ */
+
+describe('Docs Site - Embedded Course', () => {
+  beforeEach(() => {
+    // Visit the embedded course test page
+    cy.visit('/vue-skuilder/dbg/embedded-course-test.html');
+  });
+
+  it('should load the embedded course without "not found" errors', () => {
+    // Capture console errors
+    const consoleErrors: string[] = [];
+
+    cy.window().then((win) => {
+      cy.stub(win.console, 'error').callsFake((...args) => {
+        const message = args.join(' ');
+        consoleErrors.push(message);
+      });
+    });
+
+    // Wait for the data layer to initialize
+    cy.contains('Interactive study session', { timeout: 10000 }).should('be.visible');
+
+    // Check for "not found" errors in console
+    cy.window().then(() => {
+      const notFoundErrors = consoleErrors.filter(msg =>
+        msg.toLowerCase().includes('not found')
+      );
+
+      if (notFoundErrors.length > 0) {
+        throw new Error(`Found "not found" errors in console:\n${notFoundErrors.join('\n')}`);
+      }
+    });
+  });
+
+  it('should start a study session and load cards without errors', () => {
+    // Capture console errors
+    const consoleErrors: string[] = [];
+
+    cy.window().then((win) => {
+      cy.stub(win.console, 'error').callsFake((...args) => {
+        const message = args.join(' ');
+        consoleErrors.push(message);
+      });
+    });
+
+    // Wait for initialization
+    cy.contains('Interactive study session', { timeout: 10000 }).should('be.visible');
+
+    // Wait for the "Start Session" button to appear and click it
+    cy.contains('button', 'Start Session', { timeout: 10000 })
+      .should('be.visible')
+      .click();
+
+    // Wait for the init state to disappear (button should be gone)
+    cy.contains('button', 'Start Session').should('not.exist');
+
+    // Verify we're not in loading state
+    cy.contains('Loading course').should('not.exist');
+
+    // Give it a moment for card hydration
+    cy.wait(2000);
+
+    // Check for "not found" errors in console after session start
+    cy.window().then(() => {
+      const notFoundErrors = consoleErrors.filter(msg =>
+        msg.toLowerCase().includes('not found')
+      );
+
+      if (notFoundErrors.length > 0) {
+        throw new Error(`Found "not found" errors in console after session start:\n${notFoundErrors.join('\n')}`);
+      }
+    });
+
+    // Verify no error state is shown
+    cy.contains('Initialization failed').should('not.exist');
+    cy.contains('Error:').should('not.exist');
+  });
+
+  it('should load the remote course test page', () => {
+    // Test the remote course embedding as well
+    cy.visit('/vue-skuilder/dbg/remote-crs-embedding.html');
+
+    const consoleErrors: string[] = [];
+
+    cy.window().then((win) => {
+      cy.stub(win.console, 'error').callsFake((...args) => {
+        const message = args.join(' ');
+        consoleErrors.push(message);
+      });
+    });
+
+    // Wait for initialization
+    cy.contains('Interactive study session', { timeout: 10000 }).should('be.visible');
+
+    // Check for "not found" errors
+    cy.window().then(() => {
+      const notFoundErrors = consoleErrors.filter(msg =>
+        msg.toLowerCase().includes('not found')
+      );
+
+      if (notFoundErrors.length > 0) {
+        throw new Error(`Found "not found" errors in remote course test:\n${notFoundErrors.join('\n')}`);
+      }
+    });
+  });
+});
diff --git a/package.json b/package.json
index 6a774b20c..49f670a6d 100644
--- a/package.json
+++ b/package.json
@@ -26,7 +26,9 @@
     "vtag": "node scripts/vtag.js",
     "docs:dev": "vitepress dev docs",
     "docs:build": "vitepress build docs",
-    "docs:preview": "vitepress preview docs"
+    "docs:preview": "vitepress preview docs",
+    "docs:test": "cypress run",
+    "docs:test:open": "cypress open"
   },
   "private": true,
   "workspaces": [
@@ -39,6 +41,7 @@
     "@typescript-eslint/parser": "^8.25.0",
     "canvas": "^3.2.0",
     "concurrently": "^9.1.2",
+    "cypress": "^15.6.0",
     "eslint": "^9.21.0",
     "eslint-config-prettier": "^10.0.2",
     "eslint-plugin-vue": "^9.32.0",
@@ -49,6 +52,7 @@
     "vitepress": "^2.0.0-alpha.12",
     "vitepress-plugin-llms": "^1.7.5",
     "vue": "^3.5.13",
-    "vuetify": "^3.7.0"
+    "vuetify": "^3.7.0",
+    "wait-on": "^8.0.1"
   }
 }
diff --git a/tsconfig.json b/tsconfig.json
new file mode 100644
index 000000000..d15e3213c
--- /dev/null
+++ b/tsconfig.json
@@ -0,0 +1,16 @@
+{
+  "extends": "./tsconfig.base.json",
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022", "DOM"],
+    "module": "ESNext",
+    "moduleResolution": "node",
+    "types": ["cypress", "node"],
+    "esModuleInterop": true,
+    "skipLibCheck": true
+  },
+  "include": [
+    "docs/test/**/*.ts",
+    "cypress/**/*.ts"
+  ]
+}
diff --git a/yarn.lock b/yarn.lock
index 99c7e0d6c..146e4c513 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -1830,6 +1830,32 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@cypress/request@npm:^3.0.9":
+  version: 3.0.9
+  resolution: "@cypress/request@npm:3.0.9"
+  dependencies:
+    aws-sign2: "npm:~0.7.0"
+    aws4: "npm:^1.8.0"
+    caseless: "npm:~0.12.0"
+    combined-stream: "npm:~1.0.6"
+    extend: "npm:~3.0.2"
+    forever-agent: "npm:~0.6.1"
+    form-data: "npm:~4.0.4"
+    http-signature: "npm:~1.4.0"
+    is-typedarray: "npm:~1.0.0"
+    isstream: "npm:~0.1.2"
+    json-stringify-safe: "npm:~5.0.1"
+    mime-types: "npm:~2.1.19"
+    performance-now: "npm:^2.1.0"
+    qs: "npm:6.14.0"
+    safe-buffer: "npm:^5.1.2"
+    tough-cookie: "npm:^5.0.0"
+    tunnel-agent: "npm:^0.6.0"
+    uuid: "npm:^8.3.2"
+  checksum: 10c0/9ebcd3f3d49706e730671bcb0bb86488fe23a2079f12d44b6c762777118fc0286b5ce5c73fb6cacf0ae291fa89a7562ca8a2b43a2486e26906fd84a386ed6967
+  languageName: node
+  linkType: hard
+
 "@cypress/vite-dev-server@npm:^6.0.3":
   version: 6.0.3
   resolution: "@cypress/vite-dev-server@npm:6.0.3"
@@ -2284,6 +2310,29 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@hapi/address@npm:^5.1.1":
+  version: 5.1.1
+  resolution: "@hapi/address@npm:5.1.1"
+  dependencies:
+    "@hapi/hoek": "npm:^11.0.2"
+  checksum: 10c0/78138effe1e9a36fd12eb42e24adf97f3ca94b9ab1f6db65e3136cf0e5cdbd1578c14adffde18a50d776db2f326a8cb3a16d783b6705b22571a603fa47c8c3d3
+  languageName: node
+  linkType: hard
+
+"@hapi/formula@npm:^3.0.2":
+  version: 3.0.2
+  resolution: "@hapi/formula@npm:3.0.2"
+  checksum: 10c0/794d30dd13ecc070b9d93e01dacad8175c270f89bcfaa92300f843b7666d915b319d0b792694385d79270c84b52f003a4310f117202303cce3069808751f7a41
+  languageName: node
+  linkType: hard
+
+"@hapi/hoek@npm:^11.0.2, @hapi/hoek@npm:^11.0.7":
+  version: 11.0.7
+  resolution: "@hapi/hoek@npm:11.0.7"
+  checksum: 10c0/39a4a3ae9526ed66509f6d03c6eb43179a2590df6e98443328c966cfa5e7cbb9d340f61fdbe0afe092662d5377d5a611c3303c808fee26a9c9cfd6bd3737dc1c
+  languageName: node
+  linkType: hard
+
 "@hapi/hoek@npm:^9.0.0, @hapi/hoek@npm:^9.3.0":
   version: 9.3.0
   resolution: "@hapi/hoek@npm:9.3.0"
@@ -2291,6 +2340,20 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@hapi/pinpoint@npm:^2.0.1":
+  version: 2.0.1
+  resolution: "@hapi/pinpoint@npm:2.0.1"
+  checksum: 10c0/b3072f2c57c9fa2e44d85168e253e331324158509e1c45dae2676f31555326410345fd2422f890c41201e2783c5e9bb8c7b0bdcf6abe01079742a943b0c300b9
+  languageName: node
+  linkType: hard
+
+"@hapi/tlds@npm:^1.1.1":
+  version: 1.1.4
+  resolution: "@hapi/tlds@npm:1.1.4"
+  checksum: 10c0/781958d6a37b1fac741459c5ca2932cb79f1dbba18f0ca840e17d739effefecb96bd96df94296e0ca117f5b19f1c3068bb09193529300b7d99803fbec275591c
+  languageName: node
+  linkType: hard
+
 "@hapi/topo@npm:^5.1.0":
   version: 5.1.0
   resolution: "@hapi/topo@npm:5.1.0"
@@ -2300,6 +2363,15 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@hapi/topo@npm:^6.0.2":
+  version: 6.0.2
+  resolution: "@hapi/topo@npm:6.0.2"
+  dependencies:
+    "@hapi/hoek": "npm:^11.0.2"
+  checksum: 10c0/5a0079805e9a542bdb852912ce6ed3221ddd0a58569354b3900e165faabe50fb1d2d488067db97c494194835684b055828b6267be3064ac42cf2ce28db02edfc
+  languageName: node
+  linkType: hard
+
 "@highlightjs/vue-plugin@npm:^2.1.2":
   version: 2.1.2
   resolution: "@highlightjs/vue-plugin@npm:2.1.2"
@@ -4693,6 +4765,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@standard-schema/spec@npm:^1.0.0":
+  version: 1.0.0
+  resolution: "@standard-schema/spec@npm:1.0.0"
+  checksum: 10c0/a1ab9a8bdc09b5b47aa8365d0e0ec40cc2df6437be02853696a0e377321653b0d3ac6f079a8c67d5ddbe9821025584b1fb71d9cc041a6666a96f1fadf2ece15f
+  languageName: node
+  linkType: hard
+
 "@surma/rollup-plugin-off-main-thread@npm:^2.2.3":
   version: 2.2.3
   resolution: "@surma/rollup-plugin-off-main-thread@npm:2.2.3"
@@ -5754,6 +5833,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@types/tmp@npm:^0.2.3":
+  version: 0.2.6
+  resolution: "@types/tmp@npm:0.2.6"
+  checksum: 10c0/a11bfa2cd8eaa6c5d62f62a3569192d7a2c28efdc5c17af0b0551db85816b2afc8156f3ca15ac76f0b142ae1403f04f44279871424233a1f3390b2e5fc828cd0
+  languageName: node
+  linkType: hard
+
 "@types/triple-beam@npm:^1.3.2":
   version: 1.3.5
   resolution: "@types/triple-beam@npm:1.3.5"
@@ -7874,6 +7960,17 @@ __metadata:
   languageName: node
   linkType: hard
 
+"axios@npm:^1.12.1":
+  version: 1.13.2
+  resolution: "axios@npm:1.13.2"
+  dependencies:
+    follow-redirects: "npm:^1.15.6"
+    form-data: "npm:^4.0.4"
+    proxy-from-env: "npm:^1.1.0"
+  checksum: 10c0/e8a42e37e5568ae9c7a28c348db0e8cf3e43d06fcbef73f0048669edfe4f71219664da7b6cc991b0c0f01c28a48f037c515263cb79be1f1ae8ff034cd813867b
+  languageName: node
+  linkType: hard
+
 "axios@npm:^1.7.4, axios@npm:^1.7.9":
   version: 1.8.2
   resolution: "axios@npm:1.8.2"
@@ -8623,6 +8720,19 @@ __metadata:
   languageName: node
   linkType: hard
 
+"cli-table3@npm:0.6.1":
+  version: 0.6.1
+  resolution: "cli-table3@npm:0.6.1"
+  dependencies:
+    colors: "npm:1.4.0"
+    string-width: "npm:^4.2.0"
+  dependenciesMeta:
+    colors:
+      optional: true
+  checksum: 10c0/19ab1bb14bd11b3ca3557ce5ad37ef73e489ea814b99f803171e6ac0a3f2ae5fffb6dbc8864e33cdcf2a3644ebc31b488b8e624fd74af44a1c77cc365c143db4
+  languageName: node
+  linkType: hard
+
 "cli-table3@npm:^0.6.3, cli-table3@npm:~0.6.1, cli-table3@npm:~0.6.5":
   version: 0.6.5
   resolution: "cli-table3@npm:0.6.5"
@@ -8785,6 +8895,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"colors@npm:1.4.0":
+  version: 1.4.0
+  resolution: "colors@npm:1.4.0"
+  checksum: 10c0/9af357c019da3c5a098a301cf64e3799d27549d8f185d86f79af23069e4f4303110d115da98483519331f6fb71c8568d5688fa1c6523600044fd4a54e97c4efb
+  languageName: node
+  linkType: hard
+
 "colorspace@npm:1.1.x":
   version: 1.1.4
   resolution: "colorspace@npm:1.1.4"
@@ -9365,6 +9482,59 @@ __metadata:
   languageName: node
   linkType: hard
 
+"cypress@npm:^15.6.0":
+  version: 15.6.0
+  resolution: "cypress@npm:15.6.0"
+  dependencies:
+    "@cypress/request": "npm:^3.0.9"
+    "@cypress/xvfb": "npm:^1.2.4"
+    "@types/sinonjs__fake-timers": "npm:8.1.1"
+    "@types/sizzle": "npm:^2.3.2"
+    "@types/tmp": "npm:^0.2.3"
+    arch: "npm:^2.2.0"
+    blob-util: "npm:^2.0.2"
+    bluebird: "npm:^3.7.2"
+    buffer: "npm:^5.7.1"
+    cachedir: "npm:^2.3.0"
+    chalk: "npm:^4.1.0"
+    ci-info: "npm:^4.1.0"
+    cli-cursor: "npm:^3.1.0"
+    cli-table3: "npm:0.6.1"
+    commander: "npm:^6.2.1"
+    common-tags: "npm:^1.8.0"
+    dayjs: "npm:^1.10.4"
+    debug: "npm:^4.3.4"
+    enquirer: "npm:^2.3.6"
+    eventemitter2: "npm:6.4.7"
+    execa: "npm:4.1.0"
+    executable: "npm:^4.1.1"
+    extract-zip: "npm:2.0.1"
+    figures: "npm:^3.2.0"
+    fs-extra: "npm:^9.1.0"
+    hasha: "npm:5.2.2"
+    is-installed-globally: "npm:~0.4.0"
+    listr2: "npm:^3.8.3"
+    lodash: "npm:^4.17.21"
+    log-symbols: "npm:^4.0.0"
+    minimist: "npm:^1.2.8"
+    ospath: "npm:^1.2.2"
+    pretty-bytes: "npm:^5.6.0"
+    process: "npm:^0.11.10"
+    proxy-from-env: "npm:1.0.0"
+    request-progress: "npm:^3.0.0"
+    semver: "npm:^7.7.1"
+    supports-color: "npm:^8.1.1"
+    systeminformation: "npm:5.27.7"
+    tmp: "npm:~0.2.4"
+    tree-kill: "npm:1.2.2"
+    untildify: "npm:^4.0.0"
+    yauzl: "npm:^2.10.0"
+  bin:
+    cypress: bin/cypress
+  checksum: 10c0/55534a2ee8e86bb9c7adaf42aaa4160cbafb3f52f78f5d288cba48230e431565ef1654d0c626238e2122a6fb08765db7447725516e6c28c05b05b7c51f5e4624
+  languageName: node
+  linkType: hard
+
 "dashdash@npm:^1.12.0":
   version: 1.14.1
   resolution: "dashdash@npm:1.14.1"
@@ -11367,6 +11537,19 @@ __metadata:
   languageName: node
   linkType: hard
 
+"form-data@npm:^4.0.4, form-data@npm:~4.0.4":
+  version: 4.0.4
+  resolution: "form-data@npm:4.0.4"
+  dependencies:
+    asynckit: "npm:^0.4.0"
+    combined-stream: "npm:^1.0.8"
+    es-set-tostringtag: "npm:^2.1.0"
+    hasown: "npm:^2.0.2"
+    mime-types: "npm:^2.1.12"
+  checksum: 10c0/373525a9a034b9d57073e55eab79e501a714ffac02e7a9b01be1c820780652b16e4101819785e1e18f8d98f0aee866cc654d660a435c378e16a72f2e7cac9695
+  languageName: node
+  linkType: hard
+
 "form-data@npm:~4.0.0":
   version: 4.0.2
   resolution: "form-data@npm:4.0.2"
@@ -11942,6 +12125,16 @@ __metadata:
   languageName: node
   linkType: hard
 
+"hasha@npm:5.2.2":
+  version: 5.2.2
+  resolution: "hasha@npm:5.2.2"
+  dependencies:
+    is-stream: "npm:^2.0.0"
+    type-fest: "npm:^0.8.0"
+  checksum: 10c0/9d10d4e665a37beea6e18ba3a0c0399a05b26e505c5ff2fe9115b64fedb3ca95f68c89cf15b08ee4d09fd3064b5e1bfc8e8247353c7aa6b7388471d0f86dca74
+  languageName: node
+  linkType: hard
+
 "hashids@npm:^2.3.0":
   version: 2.3.0
   resolution: "hashids@npm:2.3.0"
@@ -13567,6 +13760,21 @@ __metadata:
   languageName: node
   linkType: hard
 
+"joi@npm:^18.0.1":
+  version: 18.0.1
+  resolution: "joi@npm:18.0.1"
+  dependencies:
+    "@hapi/address": "npm:^5.1.1"
+    "@hapi/formula": "npm:^3.0.2"
+    "@hapi/hoek": "npm:^11.0.7"
+    "@hapi/pinpoint": "npm:^2.0.1"
+    "@hapi/tlds": "npm:^1.1.1"
+    "@hapi/topo": "npm:^6.0.2"
+    "@standard-schema/spec": "npm:^1.0.0"
+  checksum: 10c0/b803dd46e31d90d7df92fd4cd62c2129624c9ee0ab289077ec0d8ff3959ea93216a592bf315927a73fafb19bd6eb2ad2ee58d0d8d9c56599bc23cf3de9bba8b6
+  languageName: node
+  linkType: hard
+
 "joycon@npm:^3.1.1":
   version: 3.1.1
   resolution: "joycon@npm:3.1.1"
@@ -17469,7 +17677,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"rxjs@npm:^7.2.0, rxjs@npm:^7.5.1, rxjs@npm:^7.8.1":
+"rxjs@npm:^7.2.0, rxjs@npm:^7.5.1, rxjs@npm:^7.8.1, rxjs@npm:^7.8.2":
   version: 7.8.2
   resolution: "rxjs@npm:7.8.2"
   dependencies:
@@ -18546,6 +18754,16 @@ __metadata:
   languageName: node
   linkType: hard
 
+"systeminformation@npm:5.27.7":
+  version: 5.27.7
+  resolution: "systeminformation@npm:5.27.7"
+  bin:
+    systeminformation: lib/cli.js
+  checksum: 10c0/92a9f3a2f37e135422da745be8e51984d66ae4c411e3d5c0ffdab9aef5cd8abc45d0d476bfa28c4bfee30a6e73722649544a88c4b6fa82b426c291adbfcdd8f9
+  conditions: (os=darwin | os=linux | os=win32 | os=freebsd | os=openbsd | os=netbsd | os=sunos | os=android)
+  languageName: node
+  linkType: hard
+
 "tabbable@npm:^6.2.0":
   version: 6.2.0
   resolution: "tabbable@npm:6.2.0"
@@ -18841,6 +19059,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"tmp@npm:~0.2.4":
+  version: 0.2.5
+  resolution: "tmp@npm:0.2.5"
+  checksum: 10c0/cee5bb7d674bb4ba3ab3f3841c2ca7e46daeb2109eec395c1ec7329a91d52fcb21032b79ac25161a37b2565c4858fefab927af9735926a113ef7bac9091a6e0e
+  languageName: node
+  linkType: hard
+
 "tmpl@npm:1.0.5":
   version: 1.0.5
   resolution: "tmpl@npm:1.0.5"
@@ -19270,6 +19495,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"type-fest@npm:^0.8.0":
+  version: 0.8.1
+  resolution: "type-fest@npm:0.8.1"
+  checksum: 10c0/dffbb99329da2aa840f506d376c863bd55f5636f4741ad6e65e82f5ce47e6914108f44f340a0b74009b0cb5d09d6752ae83203e53e98b1192cf80ecee5651636
+  languageName: node
+  linkType: hard
+
 "type-fest@npm:^4.18.2, type-fest@npm:^4.27.0, type-fest@npm:^4.41.0":
   version: 4.41.0
   resolution: "type-fest@npm:4.41.0"
@@ -20215,6 +20447,7 @@ __metadata:
     "@typescript-eslint/parser": "npm:^8.25.0"
     canvas: "npm:^3.2.0"
     concurrently: "npm:^9.1.2"
+    cypress: "npm:^15.6.0"
     eslint: "npm:^9.21.0"
     eslint-config-prettier: "npm:^10.0.2"
     eslint-plugin-vue: "npm:^9.32.0"
@@ -20226,6 +20459,7 @@ __metadata:
     vitepress-plugin-llms: "npm:^1.7.5"
     vue: "npm:^3.5.13"
     vuetify: "npm:^3.7.0"
+    wait-on: "npm:^8.0.1"
   languageName: unknown
   linkType: soft
 
@@ -20351,6 +20585,21 @@ __metadata:
   languageName: node
   linkType: hard
 
+"wait-on@npm:^8.0.1":
+  version: 8.0.5
+  resolution: "wait-on@npm:8.0.5"
+  dependencies:
+    axios: "npm:^1.12.1"
+    joi: "npm:^18.0.1"
+    lodash: "npm:^4.17.21"
+    minimist: "npm:^1.2.8"
+    rxjs: "npm:^7.8.2"
+  bin:
+    wait-on: bin/wait-on
+  checksum: 10c0/714825226a8b726edb43e3428bfe4d7282510309a10cc5cc280546dc4d61a30a39faa4db80a91ba6a0454831fb6dd9ad3d5a32eebc3fa2a17d48f91912dd98ec
+  languageName: node
+  linkType: hard
+
 "walker@npm:^1.0.8":
   version: 1.0.8
   resolution: "walker@npm:1.0.8"

From 29f563e7642999b1f0e96514adcb3b84f43b381d Mon Sep 17 00:00:00 2001
From: NiloCK <colin@mrkennedy.ca>
Date: Wed, 12 Nov 2025 23:18:04 -0400
Subject: [PATCH 5/5] add filesystem verification that card data written

---
 packages/cli/cypress/e2e/custom-questions-studio.cy.js | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/packages/cli/cypress/e2e/custom-questions-studio.cy.js b/packages/cli/cypress/e2e/custom-questions-studio.cy.js
index 8c2d4fa83..4eaa865d3 100644
--- a/packages/cli/cypress/e2e/custom-questions-studio.cy.js
+++ b/packages/cli/cypress/e2e/custom-questions-studio.cy.js
@@ -73,5 +73,14 @@ describe('Custom Questions - Studio Mode', () => {
     cy.contains('Course successfully saved to static files!', { timeout: 30000 }).should(
       'be.visible'
     );
+
+    // Give flush operation time to complete file writes
+    cy.wait(2000);
+
+    // Verify the flush created JSON files with our question content
+    cy.exec('find . -name "*.json" -exec grep -l "What is 2+2?" {} \\;').then((result) => {
+      expect(result.stdout.trim()).to.not.be.empty;
+      expect(result.code).to.equal(0);
+    });
   });
 });