coursecode 0.1.2 → 0.1.5

package/README.md

@@ -1,14 +1,23 @@
 # CourseCode
 
-**A modern framework for building interactive e-learning courses with AI-assisted authoring.**
+**AI-first course authoring: create interactive e-learning without writing code, then deploy to any LMS format.**
 
 Drop in your existing PDFs, Word docs, or PowerPoints — AI converts them into complete, interactive courses. No vendor lock-in, no subscriptions. Your content, your code, deployed to any LMS.
 
+## Start Here
+
+If you're creating courses (non-technical or technical), use the **[User Guide](framework/docs/USER_GUIDE.md)** as your primary documentation.
+
+- **Course authors (non-technical):** Start with the User Guide for step-by-step workflows
+- **Course authors (technical):** The User Guide is still the best starting point, then use advanced docs as needed
+- **AI assistants:** Use the AI-focused docs in `framework/docs/` (for example `COURSE_AUTHORING_GUIDE.md` and `FRAMEWORK_GUIDE.md`)
+
 ## Features
 
 - **MCP integration**: AI connects directly to your course — previews, screenshots, linting, and testing without manual file sharing
+- **No code writing required**: Describe what you want and let AI build slides, interactions, and structure
 - **Full LMS integration**: SCORM 1.2, SCORM 2004, cmi5, and LTI with complete tracking records
-- **AI-ready authoring**: Structured guides and MCP tools for AI-assisted course development
+- **AI-assisted authoring workflow**: Structured guides and MCP tools for faster course development
 - **Rich UI components**: Images, video, accordions, tabs, and custom sandboxed HTML/JS embeds
 - **Rich interactions**: Multiple choice, drag-drop, fill-in-the-blank, matching, sequencing, and more
 - **Fully accessible**: WCAG 2.1 AA compliant with dark mode, high contrast, and reduced motion
@@ -16,10 +25,9 @@ Drop in your existing PDFs, Word docs, or PowerPoints — AI converts them into
 - **Smart tracking**: Engagement requirements, learning objectives, and progress persistence
 - **Themeable design**: CSS custom properties for easy brand customization
 - **Custom endpoints**: Optional webhooks for error reporting and learning record storage
-- **Drop-in content conversion**: Feed existing PDFs, Word docs, or PowerPoint files to AI and get a complete, interactive course
 - **Live preview**: Visual editing, status dashboard, config panels, catalog browser, and full LMS simulation with debug tools
-- **[CourseCode Cloud](https://www.coursecodecloud.com)** *(coming soon)*: Deploy from CLI, share preview links, download any LMS format on demand — no rebuilds
-- **CourseCode Desktop** *(coming soon)*: Native app for Mac and Windows with AI-assisted editing, built-in preview, and no code required
+- **[CourseCode Cloud](https://www.coursecodecloud.com)**: Deploy from CLI, share preview links, download any LMS format on demand — no rebuilds
+- **CourseCode Desktop**: Native app for Mac and Windows with AI-assisted editing and built-in preview
 
 ---
 
@@ -57,7 +65,7 @@ Open `http://localhost:4173` to view and edit your course.
 
 The example course included with every new project is a complete guide to using CourseCode.
 
-**New to CourseCode?** Read the [User Guide](framework/docs/USER_GUIDE.md) for step-by-step instructions.
+**New to CourseCode?** Start with the [User Guide](framework/docs/USER_GUIDE.md). It is the primary guide for both non-technical and technical course authors.
 
 ---
 
@@ -76,7 +84,7 @@ With MCP, your AI can:
 - **Browse the component catalog** to discover available UI elements
 - **Read course state** including engagement, scoring, and LMS data
 
-See the [User Guide](framework/docs/USER_GUIDE.md#mcp-model-context-protocol) for setup instructions.
+See the [User Guide](framework/docs/USER_GUIDE.md#connecting-ai-with-mcp) for setup instructions.
 
 ---
 
@@ -171,7 +179,7 @@ The preview server provides:
 
 When ready, deploy:
 
-**With [CourseCode Cloud](https://www.coursecodecloud.com)** *(coming soon)*: Push your course and get a live link. Cloud handles hosting, generates any LMS format on demand, and gives you sharable preview links with optional password protection. No ZIP files, no manual uploads.
+**With [CourseCode Cloud](https://www.coursecodecloud.com)**: Push your course and get a live link. Cloud handles hosting, generates any LMS format on demand, and gives you sharable preview links with optional password protection. No ZIP files, no manual uploads.
 
 ```bash
 coursecode deploy
@@ -191,39 +199,20 @@ coursecode preview --export
 
 ---
 
-## CLI Commands
+## Core Commands
 
 | Command | Description |
 |---------|-------------|
 | `coursecode create <name>` | Create a new course project |
 | `coursecode preview` | Preview your course locally |
-| `coursecode build` | Build course package (ZIP for LMS upload) |
-| `coursecode build --format scorm1.2` | Build for specific LMS format |
-| `coursecode mcp` | Start the MCP server for AI integration |
-| `coursecode lint` | Validate course configuration and structure |
-| `coursecode narration` | Generate audio narration from text |
 | `coursecode convert` | Convert PDFs, Word, PowerPoint to markdown |
-| `coursecode upgrade` | Upgrade to latest version |
-
-### Cloud Commands
-
-| Command | Description |
-|---------|-------------|
-| `coursecode login` | Log in to CourseCode Cloud |
-| `coursecode logout` | Log out of CourseCode Cloud |
-| `coursecode whoami` | Show current Cloud user and organizations |
-| `coursecode courses` | List courses on CourseCode Cloud |
+| `coursecode mcp` | Start the MCP server for AI integration |
+| `coursecode lint` | Validate course structure and content |
+| `coursecode build` | Build a package for LMS upload |
 | `coursecode deploy` | Build and deploy to CourseCode Cloud |
-| `coursecode status` | Show deployment status for current course |
-
-### Output Format Options
+| `coursecode narration` | Generate audio narration from text |
 
-```bash
-coursecode build --format cmi5       # cmi5/xAPI (default, recommended)
-coursecode build --format scorm2004  # SCORM 2004 4th Edition
-coursecode build --format scorm1.2   # SCORM 1.2 (widest LMS support)
-coursecode build --format lti        # LTI 1.3
-```
+For the full command list and deployment options, see the [User Guide](framework/docs/USER_GUIDE.md#sharing-and-deploying) or run `coursecode --help`.
 
 ---
 

package/bin/cli.js

@@ -12,7 +12,7 @@
  *   coursecode new <type>     - Create new slide, assessment, or config
  *   coursecode test-errors    - Test error reporting configuration
  *   coursecode test-data      - Test data reporting configuration
- *   coursecode --version      - Show version
+ *   coursecode version         - Show version
  */
 
 import { Command } from 'commander';
@@ -30,12 +30,21 @@ program
   .description('Multi-format course authoring framework CLI')
   .version(packageJson.version);
 
+// Version command (explicit subcommand)
+program
+  .command('version')
+  .description('Show CLI version')
+  .action(() => {
+    console.log(packageJson.version);
+  });
+
 // Create command
 program
   .command('create <name>')
   .description('Create a new course project')
   .option('--blank', 'Create without example slides (clean starter)')
   .option('--no-install', 'Skip npm install')
+  .option('--start', 'Auto-start dev server after creation (skip prompt)')
   .action(async (name, options) => {
     const { create } = await import('../lib/create.js');
     await create(name, options);
@@ -280,8 +289,10 @@ program
 program
   .command('logout')
   .description('Log out of CourseCode Cloud')
-  .action(async () => {
-    const { logout } = await import('../lib/cloud.js');
+  .option('--local', 'Use local Cloud instance (http://localhost:3000)')
+  .action(async (options) => {
+    const { logout, setLocalMode } = await import('../lib/cloud.js');
+    if (options.local) setLocalMode();
     await logout();
   });
 

package/framework/docs/FRAMEWORK_GUIDE.md

@@ -513,13 +513,21 @@ try {
 
 ### External Communications
 
-Three optional, config-driven utilities for outbound communication. All in `framework/js/utilities/`, initialized in `main.js`. Each activates when its `endpoint` is configured — otherwise silently skips.
+Three optional utilities for outbound communication. All in `framework/js/utilities/`, initialized in `main.js`. Each uses a **priority chain** for configuration:
 
-| Utility | Config Key | Transport | Events |
-|---------|-----------|-----------|--------|
-| `error-reporter.js` | `environment.errorReporting` | POST per error (60s dedup) | `*:error` (14 event types) |
-| `data-reporter.js` | `environment.dataReporting` | Batched POST + `sendBeacon` on unload | `assessment:submitted`, `objective:updated`, `interaction:recorded` |
-| `course-channel.js` | `environment.channel` | POST to send, SSE to receive | `channel:message`, `channel:connected`, `channel:disconnected` |
+```
+1. <meta name="cc-*"> tag in HTML        → Injected by CourseCode Cloud (highest priority)
+2. environment.* in course-config.js     → Author-defined (self-hosted fallback)
+3. Skip                                  → Feature disabled (silent)
+```
+
+When cloud meta tags are present, they **always win** — even if `course-config.js` also has values. This ensures cloud-served courses always report to the correct endpoints.
+
+| Utility | Config Key | Meta Tag | Transport | Events |
+|---------|-----------|----------|-----------|--------|
+| `error-reporter.js` | `environment.errorReporting` | `cc-error-endpoint` | POST per error (60s dedup) | `*:error` (14 event types) |
+| `data-reporter.js` | `environment.dataReporting` | `cc-data-endpoint` | Batched POST + `sendBeacon` on unload | `assessment:submitted`, `objective:updated`, `interaction:recorded` |
+| `course-channel.js` | `environment.channel` | `cc-channel-endpoint` + `cc-channel-id` | POST to send, SSE to receive | `channel:message`, `channel:connected`, `channel:disconnected` |
 
 **Error Reporter** — Subscribes to all `*:error` events, deduplicates by domain+operation+message (60s window), POSTs to endpoint. Optional `enableUserReports: true` adds "Report Issue" to settings menu. `submitUserReport()` for programmatic user reports.
 
@@ -528,7 +536,7 @@ Three optional, config-driven utilities for outbound communication. All in `fram
 **Course Channel** — Generic pub/sub pipe. `sendChannelMessage(data)` POSTs any JSON to `endpoint/channelId`. SSE listener on same URL bridges incoming messages to EventBus. Exponential backoff reconnect (1s → 30s cap). Content-agnostic — the relay is a dumb fan-out router.
 
 ```javascript
-// Config (all optional)
+// Self-hosted config (all optional)
 environment: {
     errorReporting: { endpoint: '...', apiKey: '...', includeContext: true, enableUserReports: true },
     dataReporting:  { endpoint: '...', apiKey: '...', batchSize: 10, flushInterval: 30000 },
@@ -536,7 +544,20 @@ environment: {
 }
 ```
 
-**Authentication** — All reporters support an optional `apiKey` field. When set, it's sent as `Authorization: Bearer <apiKey>` on `fetch()` calls. For `sendBeacon` (page unload), `fetch()` with `keepalive: true` is used instead since `sendBeacon` doesn't support custom headers. For SSE (`EventSource`), the token is passed as a `?token=` URL parameter.
+**Cloud meta tags** (injected into `<head>` by CourseCode Cloud):
+```html
+<meta name="cc-error-endpoint" content="https://engine.example.com/errors">
+<meta name="cc-data-endpoint" content="https://engine.example.com/data">
+<meta name="cc-channel-endpoint" content="https://engine.example.com/channel">
+<meta name="cc-channel-id" content="session-abc123">
+<meta name="cc-api-key" content="sk_live_abc123">
+<meta name="cc-license-id" content="lic_xyz">
+<meta name="cc-course-id" content="course_456">
+```
+
+**Authentication** — All reporters support an optional `apiKey` field (from config or `cc-api-key` meta tag). When set, it's sent as `Authorization: Bearer <apiKey>` on `fetch()` calls. For `sendBeacon` (page unload), `fetch()` with `keepalive: true` is used instead since `sendBeacon` doesn't support custom headers. For SSE (`EventSource`), the token is passed as a `?token=` URL parameter.
+
+**Cloud attribution** — When `cc-license-id` and `cc-course-id` meta tags are present (LTI/cmi5 launches), error and data reporters include `licenseId` and `courseId` in all payloads for engine routing.
 
 **Example backends:** `framework/docs/examples/cloudflare-{error-worker,data-worker,channel-relay}.js`
 
@@ -838,15 +859,35 @@ If the preview is not running, runtime tools fail fast with a clear error messag
 | `coursecode_state` | Full course snapshot | `{slide, structure, interactions, engagement, lmsState, errors}` |
 | `coursecode_navigate` | Go to slide by ID | `{slideId}` → new state |
 | `coursecode_interact` | Set response + evaluate | `{interactionId, response}` → `{correct, score, feedback}` |
-| `coursecode_screenshot` | Visual capture (PNG) | Optional `slideId` to navigate first, `fullPage` for scroll capture |
+| `coursecode_screenshot` | Visual capture (JPEG) | Optional `slideId` to navigate first, `fullPage` for scroll capture |
+| `coursecode_viewport` | Set viewport size | Breakpoint name or `{width, height}` → persists until changed |
 | `coursecode_reset` | Clear learner state | `{hard?: boolean}` → reload |
 
+### Screenshot Quality Modes
+
+Two quality modes optimize for token efficiency — **neither changes the viewport**:
+
+| Mode | Quality | Typical Size | Use For |
+|------|---------|-------------|---------|
+| normal (default) | JPEG@50 | ~20-40KB | Layout checks |
+| detailed | JPEG@90 | ~100-200KB | Close text/element inspection |
+
+### Viewport Control
+
+Use `coursecode_viewport` for responsive design testing. Two input modes:
+
+- **Breakpoint name**: `"mobile-portrait"`, `"tablet-landscape"`, etc. — resolved dynamically from the running course's `breakpointManager.getBreakpoints()`, so always in sync with CSS.
+- **Explicit dimensions**: `{width: 375, height: 812}` for specific device sizes.
+
+The viewport **persists** until explicitly changed again. Default is 1280×720.
+
 ### Navigation API
 
 Use MCP tools for all course interaction — never use external browser tools:
 
 - `coursecode_state` → get all slide IDs, current position, interactions
 - `coursecode_navigate(slideId)` → instant slide navigation
+- `coursecode_viewport(breakpoint)` → set viewport for responsive testing
 - `coursecode_screenshot(slideId)` → navigate + capture in one call
 - `coursecode_interact(id, response)` → answer + evaluate in one call
 

package/framework/docs/USER_GUIDE.md

@@ -10,6 +10,7 @@ A complete guide to creating interactive e-learning courses with AI assistance.
    - [What You'll Need](#what-youll-need)
    - [Installation](#installation)
    - [Creating Your First Project](#creating-your-first-project)
+   - [Importing a PowerPoint (Optional)](#importing-a-powerpoint-optional)
 2. [Your Course Folder](#your-course-folder)
    - [Where Everything Lives](#where-everything-lives)
    - [The Documentation Files](#the-documentation-files)
@@ -40,11 +41,15 @@ A complete guide to creating interactive e-learning courses with AI assistance.
    - [Navigation and Flow](#navigation-and-flow)
    - [Engagement Requirements](#engagement-requirements)
    - [Learning Objectives](#learning-objectives)
+   - [Course Completion Feedback](#course-completion-feedback)
+   - [Updating Live Courses Safely](#updating-live-courses-safely)
 8. [Sharing and Deploying](#sharing-and-deploying)
    - [Sharing Previews](#sharing-previews)
+   - [Preview Export Options](#preview-export-options)
    - [Understanding LMS Formats](#understanding-lms-formats)
    - [Standard Deployment](#standard-deployment)
    - [CDN Deployment (Advanced)](#cdn-deployment-advanced)
+   - [Cloud Deployment](#cloud-deployment)
    - [Exporting Content for Review](#exporting-content-for-review)
 9. [Generating Audio Narration](#generating-audio-narration)
 10. [Troubleshooting](#troubleshooting)
@@ -107,6 +112,22 @@ coursecode new assessment final-quiz  # Create a graded quiz
 coursecode new config                 # Create a fresh course-config.js
 ```
 
+### Importing a PowerPoint (Optional)
+
+If you already have a PowerPoint deck, you can import it directly as a presentation-style course:
+
+```bash
+coursecode import my-deck.pptx
+```
+
+On macOS, CourseCode can drive Microsoft PowerPoint to export slides automatically. On any platform, you can use pre-exported slide images:
+
+```bash
+coursecode import my-deck.pptx --slides-dir ./exported-slides
+```
+
+This creates a project with slide image files, generated slide pages, and extracted text in `course/references/converted/` for AI-assisted enhancement.
+
 ---
 
 ## Your Course Folder
@@ -274,6 +295,7 @@ Once connected, your AI assistant gains these capabilities:
 | `coursecode_component_catalog` | Browse available UI components (tabs, accordion, cards, etc.) |
 | `coursecode_interaction_catalog` | Browse available interaction types (multiple choice, drag-drop, etc.) |
 | `coursecode_css_catalog` | Browse available CSS classes by category |
+| `coursecode_icon_catalog` | Browse available icons by name/category |
 | `coursecode_workflow_status` | Get guidance on what to do next based on your project's current state |
 | `coursecode_build` | Build the course for LMS deployment |
 
@@ -459,6 +481,35 @@ Track what learners have accomplished:
 - Link objectives to assessment scores
 - Report completion status to your LMS
 
+### Course Completion Feedback
+
+CourseCode can show an end-of-course feedback section in the completion modal. You can enable:
+
+- A 5-star rating
+- A free-text comments field
+
+Configure this in `course/course-config.js`:
+
+```javascript
+completion: {
+  promptForRating: true,
+  promptForComments: true
+}
+```
+
+Set either option to `false` if you do not want to collect that input.
+
+### Updating Live Courses Safely
+
+When you update a course structure after learners have already started (for example, add/remove slides or change assessments), stored LMS state may no longer match the new structure.
+
+CourseCode includes validation and recovery behavior:
+
+- In development, mismatches are surfaced as errors so you can fix issues early
+- In production, CourseCode attempts graceful recovery to keep learners moving
+
+Best practice: set and increment `metadata.version` in `course/course-config.js` whenever you make meaningful structural changes.
+
 ---
 
 ## Sharing and Deploying
@@ -473,6 +524,24 @@ coursecode preview --export
 
 This creates a self-contained folder you can upload to any web host (Netlify, GitHub Pages, etc.). You can add password protection and other options — ask your AI assistant for help.
 
+### Preview Export Options
+
+Useful `coursecode preview --export` options:
+
+```bash
+coursecode preview --export -o ./course-preview
+coursecode preview --export --password "secret"
+coursecode preview --export --skip-build
+coursecode preview --export --nojekyll
+coursecode preview --export --no-content
+```
+
+- `-o, --output`: choose output folder
+- `-p, --password`: add password protection to shared preview
+- `--skip-build`: export from existing `dist/` without rebuilding
+- `--nojekyll`: add `.nojekyll` (important for GitHub Pages)
+- `--no-content`: hide the content viewer panel in exported preview
+
 ### Understanding LMS Formats
 
 An LMS (Learning Management System) is the platform your organization uses to deliver training — think Cornerstone, Moodle, Canvas, Docebo, etc. CourseCode packages your course in a format your LMS understands.
@@ -486,6 +555,8 @@ An LMS (Learning Management System) is the platform your organization uses to de
 
 **Not sure which to pick?** Ask your LMS administrator. If they don't know, try **SCORM 1.2** — it works with almost everything.
 
+> **SCORM 1.2 caveat:** SCORM 1.2 has a strict ~4KB suspend data limit. CourseCode uses a strict storage mode to fit within that limit, which can reduce how much interaction UI state is restored across slides on resume.
+
 > **Using CourseCode Cloud?** You don't need to choose a format. Cloud-deployed courses use a universal build — the cloud generates the correct format automatically when you download a ZIP for your LMS. The format setting in `course-config.js` only applies to local `coursecode build` commands.
 
 ### Standard Deployment
@@ -514,6 +585,19 @@ For teams that update courses frequently or serve multiple LMS clients, CourseCo
 
 CDN deployment uses special format variants (`scorm1.2-proxy`, `scorm2004-proxy`, `cmi5-remote`). Ask your AI assistant to set this up — it involves configuring an external URL and access tokens in `course-config.js`.
 
+Generate and add client tokens with:
+
+```bash
+coursecode token --add client-a
+coursecode token --add client-b
+```
+
+Then build your proxy/remote package and deploy:
+
+```bash
+coursecode build --format scorm1.2-proxy
+```
+
 ### Cloud Deployment
 
 CourseCode Cloud is the simplest deployment option. Upload your course once and the cloud handles everything:
@@ -576,6 +660,18 @@ Audio files are generated to `course/assets/audio/` and automatically linked to
 - Make sure you're giving it the right documentation files
 - Share error messages so it can fix issues
 
+**MCP tools are connected but runtime actions fail**
+- Make sure `coursecode preview` is running in the same project
+- Runtime MCP tools (state, navigate, screenshot, interact, reset) require a live preview connection
+
+**Cloud/local format behavior is confusing**
+- Local builds use your selected `--format` (or config default)
+- Cloud deploy uses a universal build and lets you choose format at download time
+
+**Returning learners see unexpected progress after major course updates**
+- If you changed slide structure or assessments, old stored LMS state may not fully match new content
+- Increment `metadata.version` and re-test resume behavior in preview and LMS
+
 **Need more help?**
 - Check the [GitHub issues](https://github.com/course-code-framework/coursecode/issues)
 - The example course includes troubleshooting tips

package/framework/js/managers/objective-manager.js

@@ -140,6 +140,13 @@ class ObjectiveManager {
             throw new Error('ObjectiveManager: setObjective requires an id.');
         }
 
+        if (objectiveData.score !== undefined && objectiveData.score !== null) {
+            const score = objectiveData.score;
+            if (typeof score !== 'number' || !Number.isFinite(score) || score < 0 || score > 100) {
+                throw new Error(`ObjectiveManager: Score must be a number between 0 and 100, got ${score}`);
+            }
+        }
+
         const existing = this.objectives[id] || { id };
         const updated = { ...existing, ...objectiveData };
 
@@ -151,7 +158,7 @@ class ObjectiveManager {
         eventBus.emit('objective:updated', updated);
 
         // Emit specific score event if score was updated (for ScoreManager)
-        if (typeof updated.score === 'number') {
+        if (typeof updated.score === 'number' && Number.isFinite(updated.score)) {
             eventBus.emit('objective:score:updated', {
                 objectiveId: id,
                 score: updated.score
@@ -272,6 +279,15 @@ class ObjectiveManager {
             this._checkTimeBasedObjectives(view);
         });
 
+        // Re-evaluate time-based objectives for the slide just left.
+        // Slide durations are finalized on navigation:beforeChange, so fromSlideId
+        // is the reliable key to check after navigation completes.
+        eventBus.on('navigation:changed', ({ fromSlideId }) => {
+            if (fromSlideId) {
+                this._checkTimeBasedObjectives(fromSlideId);
+            }
+        });
+
         // Listen for flag changes to track flag-based objectives
         eventBus.on('flag:updated', ({ key, value }) => {
             this._checkFlagBasedObjectives(key, value);
@@ -318,6 +334,10 @@ class ObjectiveManager {
 
                 case 'allSlidesVisited': {
                     const requiredSlides = criteria.slideIds || [];
+                    if (!Array.isArray(requiredSlides) || requiredSlides.length === 0) {
+                        logger.warn(`[ObjectiveManager] Objective "${objective.id}" has invalid allSlidesVisited criteria: slideIds must be a non-empty array.`);
+                        break;
+                    }
                     const allVisited = requiredSlides.every(sid => allVisitedSlides.has(sid));
                     if (allVisited) {
                         this.setCompletionStatus(objective.id, 'completed');
@@ -352,8 +372,14 @@ class ObjectiveManager {
             if (criteria.type === 'timeOnSlide' && criteria.slideId === slideId) {
                 const totalMilliseconds = slideDurations[slideId] || 0;
                 const totalSeconds = totalMilliseconds / 1000;
+                const minSeconds = criteria.minSeconds;
 
-                if (totalSeconds >= (criteria.minSeconds || 0)) {
+                if (typeof minSeconds !== 'number' || !Number.isFinite(minSeconds) || minSeconds <= 0) {
+                    logger.warn(`[ObjectiveManager] Objective "${objective.id}" has invalid timeOnSlide criteria: minSeconds must be a positive number.`);
+                    return;
+                }
+
+                if (totalSeconds >= minSeconds) {
                     this.setCompletionStatus(objective.id, 'completed');
                     logger.debug(`[ObjectiveManager] Objective "${objective.id}" completed: timeOnSlide (${totalSeconds.toFixed(1)}s)`);
                 }
@@ -400,6 +426,10 @@ class ObjectiveManager {
             } else if (criteria.type === 'allFlags') {
                 // Multiple flags check - all must be truthy (or match equals values)
                 const requiredFlags = criteria.flags || [];
+                if (!Array.isArray(requiredFlags) || requiredFlags.length === 0) {
+                    logger.warn(`[ObjectiveManager] Objective "${objective.id}" has invalid allFlags criteria: flags must be a non-empty array.`);
+                    return;
+                }
                 const allMet = requiredFlags.every(flagConfig => {
                     const key = typeof flagConfig === 'string' ? flagConfig : flagConfig.key;
                     const value = flags[key];

package/framework/js/navigation/NavigationActions.js

@@ -696,9 +696,6 @@ async function _performNavigation(slideId, context = {}, updateBookmark = true)
     _setupEngagementListeners(newSlide);
     _updateEngagementIndicator(newSlide);
 
-    // Start timer for the new slide
-    AppActions.startSessionTimer(slideId);
-
     // Update progress measure to reflect slide visit
     // Count only sequential slides (excludes remedial/conditional slides)
     const totalSequentialSlides = slides.filter(s => isSlideInSequence(s, stateManager, assessmentConfigs)).length;

package/framework/js/navigation/navigation-helpers.js

@@ -154,11 +154,15 @@ export function evaluateGatingCondition(condition, stateManager, assessmentConfi
         }
 
         case 'timeOnSlide': {
+            const minSeconds = condition.minSeconds;
+            if (typeof minSeconds !== 'number' || !Number.isFinite(minSeconds) || minSeconds <= 0) {
+                return false;
+            }
             const sessionData = stateManager.getDomainState('sessionData');
             const slideDurations = sessionData?.slideDurations || {};
             const slideDurationMs = slideDurations[condition.slideId] || 0;
             const totalSeconds = slideDurationMs / 1000;
-            return totalSeconds >= (condition.minSeconds || 0);
+            return totalSeconds >= minSeconds;
         }
 
         case 'custom': {

package/framework/js/utilities/course-channel.js

@@ -23,6 +23,12 @@
 import { eventBus } from '../core/event-bus.js';
 import { logger } from './logger.js';
 
+// ── Cloud meta tag reader ───────────────────────────────────────────
+function getMetaContent(name) {
+    const el = document.querySelector(`meta[name="${name}"]`);
+    return el ? el.getAttribute('content') : null;
+}
+
 // Connection state
 let _config = null;
 let _eventSource = null;
@@ -186,7 +192,16 @@ function handleUnload() {
  * @param {Object} courseConfig - The course configuration object
  */
 export function initCourseChannel(courseConfig) {
-    const config = courseConfig.environment?.channel;
+    // Priority chain: meta tags (cloud-injected) → config (self-hosted) → disabled
+    const metaEndpoint = getMetaContent('cc-channel-endpoint');
+    const metaChannelId = getMetaContent('cc-channel-id');
+    let config;
+    if (metaEndpoint && metaChannelId) {
+        // Both required — endpoint alone without a channel ID is useless
+        config = { endpoint: metaEndpoint, channelId: metaChannelId, apiKey: getMetaContent('cc-api-key') };
+    } else {
+        config = courseConfig.environment?.channel;
+    }
 
     _config = config;
 

package/framework/js/utilities/data-reporter.js

@@ -18,6 +18,12 @@
 import { eventBus } from '../core/event-bus.js';
 import { logger } from './logger.js';
 
+// ── Cloud meta tag reader ───────────────────────────────────────────
+function getMetaContent(name) {
+    const el = document.querySelector(`meta[name="${name}"]`);
+    return el ? el.getAttribute('content') : null;
+}
+
 // Batching state
 let batch = [];
 let flushTimer = null;
@@ -25,6 +31,8 @@ let flushTimer = null;
 // Configuration
 let _config = null;
 let _courseConfig = null;
+let _licenseId = null;
+let _courseId = null;
 
 const DEFAULT_BATCH_SIZE = 10;
 const DEFAULT_FLUSH_INTERVAL = 30000; // 30 seconds
@@ -158,6 +166,10 @@ function buildPayload(records) {
         };
     }
 
+    // Cloud attribution context (license and course IDs for engine routing)
+    if (_licenseId) payload.licenseId = _licenseId;
+    if (_courseId) payload.courseId = _courseId;
+
     return payload;
 }
 
@@ -238,11 +250,6 @@ function handleBeforeTerminate() {
  * @param {Object} courseConfig - The course configuration object
  */
 export function initDataReporter(courseConfig) {
-    const config = courseConfig.environment?.dataReporting;
-
-    _config = config;
-    _courseConfig = courseConfig;
-
     // Never send data during local dev — the preview server and dev command
     // inject VITE_COURSECODE_LOCAL into the Vite build env, which is auto-exposed
     // to client code. Production builds via `coursecode build` don't set this.
@@ -251,6 +258,22 @@ export function initDataReporter(courseConfig) {
         return;
     }
 
+    // Priority chain: meta tags (cloud-injected) → config (self-hosted) → disabled
+    const metaEndpoint = getMetaContent('cc-data-endpoint');
+    let config;
+    if (metaEndpoint) {
+        config = { endpoint: metaEndpoint, apiKey: getMetaContent('cc-api-key') };
+    } else {
+        config = courseConfig.environment?.dataReporting;
+    }
+
+    _config = config;
+    _courseConfig = courseConfig;
+
+    // Cloud attribution (present when launched via LTI/cmi5)
+    _licenseId = getMetaContent('cc-license-id');
+    _courseId = getMetaContent('cc-course-id');
+
     // Disabled if no endpoint configured
     if (!config?.endpoint) {
         logger.debug('[DataReporter] Not configured, skipping initialization');

package/framework/js/utilities/error-reporter.js

@@ -42,6 +42,12 @@ const sendTimestamps = [];     // Timestamps of recent sends
 // ── Re-entrancy guard ───────────────────────────────────────────────
 let _isReporting = false;
 
+// ── Cloud meta tag reader ───────────────────────────────────────────
+function getMetaContent(name) {
+    const el = document.querySelector(`meta[name="${name}"]`);
+    return el ? el.getAttribute('content') : null;
+}
+
 /**
  * Generate a unique key for an error to detect duplicates
  */
@@ -172,6 +178,10 @@ async function flushBatch(config, courseConfig) {
         };
     }
 
+    // Cloud attribution context (license and course IDs for engine routing)
+    if (_licenseId) request.licenseId = _licenseId;
+    if (_courseId) request.courseId = _courseId;
+
     // Guard re-entrancy: our own logger calls must not trigger new reports
     _isReporting = true;
     try {
@@ -201,6 +211,8 @@ async function flushBatch(config, courseConfig) {
 // Store config globally for user reports
 let _config = null;
 let _courseConfig = null;
+let _licenseId = null;
+let _courseId = null;
 
 /**
  * Check if error reporting is configured and user reports are enabled
@@ -239,6 +251,10 @@ export async function submitUserReport(description, options = {}) {
             id: _courseConfig.metadata?.id
         };
     }
+
+    // Cloud attribution
+    if (_licenseId) payload.licenseId = _licenseId;
+    if (_courseId) payload.courseId = _courseId;
     
     // Include current slide info if available
     if (options.currentSlide) {
@@ -279,12 +295,6 @@ export async function submitUserReport(description, options = {}) {
  * @param {Object} courseConfig - The course configuration object
  */
 export function initErrorReporter(courseConfig) {
-    const config = courseConfig.environment?.errorReporting;
-    
-    // Store for user reports
-    _config = config;
-    _courseConfig = courseConfig;
-    
     // Never send reports during local dev — the preview server and dev command
     // inject VITE_COURSECODE_LOCAL into the Vite build env, which is auto-exposed
     // to client code. Production builds via `coursecode build` don't set this.
@@ -292,15 +302,32 @@ export function initErrorReporter(courseConfig) {
         logger.debug('[ErrorReporter] Disabled in local dev mode');
         return;
     }
-    
+
+    // Priority chain: meta tags (cloud-injected) → config (self-hosted) → disabled
+    const metaEndpoint = getMetaContent('cc-error-endpoint');
+    let config;
+    if (metaEndpoint) {
+        config = { endpoint: metaEndpoint, apiKey: getMetaContent('cc-api-key') };
+    } else {
+        config = courseConfig.environment?.errorReporting;
+    }
+
+    // Store for user reports
+    _config = config;
+    _courseConfig = courseConfig;
+
+    // Cloud attribution (present when launched via LTI/cmi5)
+    _licenseId = getMetaContent('cc-license-id');
+    _courseId = getMetaContent('cc-course-id');
+
     // Disabled if not configured or no endpoint
     if (!config?.endpoint) {
         logger.debug('[ErrorReporter] Not configured, skipping initialization');
         return;
     }
-    
+
     logger.info('[ErrorReporter] Initialized with endpoint:', config.endpoint);
-    
+
     // Subscribe to unified logger events
     eventBus.on('log:error', (errorData) => {
         if (_isReporting) return; // prevent re-entrancy from our own logger calls

package/lib/create.js

@@ -211,10 +211,8 @@ export async function create(name, options = {}) {
 `);
   }
 
-  // Prompt to start dev server
-  const shouldStart = await promptYesNo('   Start the development server? (Y/n) ');
-
-  if (shouldStart) {
+  // --start: auto-start dev server. Otherwise print instructions and exit.
+  if (options.start) {
     console.log('\n   Starting development server...\n');
     const child = spawn('npx', ['coursecode', 'dev'], {
       cwd: targetDir,
@@ -227,22 +225,7 @@ export async function create(name, options = {}) {
       console.log(`      cd ${name} && coursecode dev\n`);
     });
   } else {
-    console.log(`
-   To start developing:
-
-      cd ${name}
-      coursecode dev
-`);
+    console.log(`\n   To start developing:\n\n      cd ${name}\n      coursecode dev\n`);
   }
 }
 
-function promptYesNo(question) {
-  return new Promise((resolve) => {
-    process.stdout.write(question);
-    process.stdin.setEncoding('utf8');
-    process.stdin.once('data', (data) => {
-      const answer = data.trim().toLowerCase();
-      resolve(answer === '' || answer === 'y' || answer === 'yes');
-    });
-  });
-}

package/lib/headless-browser.js

@@ -71,6 +71,7 @@ class HeadlessBrowser {
         this._reconnectTimer = null;
         this._stopped = false;
         this._consoleLogs = [];
+        this._viewport = { width: 1280, height: 720 };
     }
 
     /**
@@ -106,7 +107,7 @@ class HeadlessBrowser {
         });
 
         this.page = await this.browser.newPage();
-        await this.page.setViewport({ width: 1280, height: 720 });
+        await this.page.setViewport(this._viewport);
 
         // Capture console warnings and errors
         this._consoleLogs = [];
@@ -250,20 +251,88 @@ class HeadlessBrowser {
         return logs;
     }
 
+    /**
+     * Set the headless browser viewport size.
+     * Accepts either a dimensions object or a named breakpoint string.
+     * The viewport persists until explicitly changed again.
+     *
+     * @param {object|string} sizeOrBreakpoint - {width, height} or breakpoint name
+     * @returns {Promise<{width: number, height: number, breakpoint?: string}>} Applied viewport
+     */
+    async setViewport(sizeOrBreakpoint) {
+        this._ensureRunning();
+
+        let width, height, breakpointName;
+
+        if (typeof sizeOrBreakpoint === 'string') {
+            // Resolve breakpoint name dynamically from the running course
+            breakpointName = sizeOrBreakpoint;
+            await this._ensureCourseFrame();
+            const bp = await this.courseFrame.evaluate((name) => {
+                const bpManager = window.CourseCode?.breakpointManager;
+                if (!bpManager) return null;
+                const breakpoints = bpManager.getBreakpoints();
+                return breakpoints.find(b => b.name === name) || null;
+            }, breakpointName);
+
+            if (!bp) {
+                // Get available names for error message
+                const available = await this.courseFrame.evaluate(() => {
+                    const bpManager = window.CourseCode?.breakpointManager;
+                    if (!bpManager) return [];
+                    return bpManager.getBreakpoints().map(b => b.name);
+                });
+                throw new Error(
+                    `Unknown breakpoint "${breakpointName}". ` +
+                    `Available: ${available.join(', ')}`
+                );
+            }
+
+            // Use the breakpoint's boundary width
+            width = bp.maxWidth ?? bp.minWidth;
+            // Scale height proportionally from the 16:9 base (1280x720)
+            height = Math.round(width * (9 / 16));
+        } else {
+            width = sizeOrBreakpoint.width;
+            height = sizeOrBreakpoint.height;
+            if (!width || !height) {
+                throw new Error('Viewport requires both width and height, or a breakpoint name string.');
+            }
+        }
+
+        this._viewport = { width, height };
+        await this.page.setViewport(this._viewport);
+        // Brief settle for layout reflow
+        await new Promise(resolve => setTimeout(resolve, 100));
+
+        return { width, height, ...(breakpointName ? { breakpoint: breakpointName } : {}) };
+    }
+
+    /**
+     * Get the current viewport dimensions.
+     * @returns {{width: number, height: number}}
+     */
+    getViewport() {
+        return { ...this._viewport };
+    }
+
     /**
      * Take a screenshot of the current page.
-     * 
+     *
      * Two quality modes optimize for token efficiency:
-     * - normal (default): 800×450 JPEG@70 (~30-60KB) — quick layout checks
-     * - detailed: 1280×720 JPEG@90 (~100-200KB) — close text/element inspection
-     * 
+     * - normal (default): JPEG@50 (~20-40KB) — quick layout checks
+     * - detailed: JPEG@90 (~100-200KB) — close text/element inspection
+     *
+     * Neither mode changes the viewport. The screenshot captures at the
+     * current viewport size. Use setViewport() to change viewport independently.
+     *
      * fullPage captures the entire scrollable course content by screenshotting
      * the course iframe element directly (bypasses the stub player chrome).
-     * 
+     *
      * @param {object} options
      * @param {string} [options.slideId] - Navigate to this slide before screenshotting
      * @param {boolean} [options.fullPage=false] - Capture full scrollable content
-     * @param {boolean} [options.detailed=false] - Use high-res detailed mode
+     * @param {boolean} [options.detailed=false] - Higher JPEG quality for close inspection
      * @returns {Promise<{data: string, mimeType: string}>} Base64-encoded JPEG
      */
     async screenshot(options = {}) {
@@ -271,10 +340,8 @@ class HeadlessBrowser {
 
         const { slideId, fullPage = false, detailed = false, scrollY } = options;
 
-        // Screenshot quality presets
-        const preset = detailed
-            ? { width: 1280, height: 720, quality: 90 }
-            : { width: 800, height: 450, quality: 70 };
+        // Quality-only presets — viewport is NOT changed
+        const quality = detailed ? 90 : 50;
 
         // Navigate to specific slide if requested
         if (slideId) {
@@ -297,18 +364,11 @@ class HeadlessBrowser {
             await new Promise(resolve => setTimeout(resolve, 100));
         }
 
-        // Resize viewport for the chosen mode
-        await this.page.setViewport({ width: preset.width, height: preset.height });
-        // Brief settle after resize
-        await new Promise(resolve => setTimeout(resolve, 100));
-
         let screenshotBuffer;
 
         if (fullPage) {
             // For fullPage, measure the iframe content's full scrollable height,
             // temporarily expand the viewport so nothing is clipped, then screenshot.
-            // ElementHandle.screenshot() only captures the element's bounding box,
-            // so we need to make the viewport tall enough to show everything.
             await this._ensureCourseFrame();
             const contentHeight = await this.courseFrame.evaluate(() => {
                 return Math.max(
@@ -317,33 +377,33 @@ class HeadlessBrowser {
                 );
             });
 
-            const fullHeight = Math.max(contentHeight, preset.height);
-            await this.page.setViewport({ width: preset.width, height: fullHeight });
+            const fullHeight = Math.max(contentHeight, this._viewport.height);
+            await this.page.setViewport({ width: this._viewport.width, height: fullHeight });
             await new Promise(resolve => setTimeout(resolve, 200));
 
             const iframeElement = await this.page.$('iframe');
             if (iframeElement) {
                 screenshotBuffer = await iframeElement.screenshot({
                     type: 'jpeg',
-                    quality: preset.quality
+                    quality
                 });
             } else {
                 screenshotBuffer = await this.page.screenshot({
                     type: 'jpeg',
-                    quality: preset.quality,
+                    quality,
                     fullPage: true
                 });
             }
+
+            // Restore viewport height (fullPage temporarily expanded it)
+            await this.page.setViewport(this._viewport);
         } else {
             screenshotBuffer = await this.page.screenshot({
                 type: 'jpeg',
-                quality: preset.quality
+                quality
             });
         }
 
-        // Restore default viewport
-        await this.page.setViewport({ width: 1280, height: 720 });
-
         return {
             data: screenshotBuffer.toString('base64'),
             mimeType: 'image/jpeg'

package/lib/mcp-prompts.js

@@ -121,9 +121,11 @@ Requires preview server to be running.`,
         name: 'coursecode_screenshot',
         description: `Take a screenshot of the course preview. Returns a JPEG image.
 
-Two modes optimized for token efficiency:
-- normal (default): 800×450 (~30-60KB) — layout checks
-- detailed: 1280×720 (~100-200KB) — close text/element inspection
+Two quality modes (neither changes viewport):
+- normal (default): JPEG@50 (~20-40KB) — layout checks
+- detailed: JPEG@90 (~100-200KB) — close text/element inspection
+
+Captures at the current viewport size. Use coursecode_viewport to change viewport for responsive testing.
 
 Use scrollY to scroll course content before capturing (useful for long slides).
 fullPage captures the course iframe's full content area.
@@ -143,7 +145,7 @@ Requires preview server to be running.`,
                 },
                 detailed: {
                     type: 'boolean',
-                    description: 'Use higher-res mode (1280×720) for close inspection'
+                    description: 'Higher JPEG quality for close inspection (does not change viewport)'
                 },
                 scrollY: {
                     type: 'number',
@@ -153,6 +155,41 @@ Requires preview server to be running.`,
             required: []
         }
     },
+    {
+        name: 'coursecode_viewport',
+        description: `Set the headless browser viewport size for responsive design testing.
+
+Two modes:
+- Breakpoint name: 'mobile-portrait', 'mobile-landscape', 'tablet-portrait', etc.
+  Resolves width dynamically from the course's breakpoint manager (always in sync with CSS).
+  Height scales proportionally (16:9).
+- Explicit dimensions: {width: 375, height: 812} for specific device sizes.
+
+The viewport PERSISTS until changed again. Call with 'desktop' or {width: 1280, height: 720} to reset.
+
+Returns the applied viewport dimensions and breakpoint name (if used).
+
+Use before coursecode_screenshot to test responsive layouts.
+Requires preview server to be running.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                breakpoint: {
+                    type: 'string',
+                    description: 'Named breakpoint from the course (e.g., "mobile-portrait", "tablet-landscape", "desktop")'
+                },
+                width: {
+                    type: 'number',
+                    description: 'Explicit viewport width in pixels (use with height)'
+                },
+                height: {
+                    type: 'number',
+                    description: 'Explicit viewport height in pixels (use with width)'
+                }
+            },
+            required: []
+        }
+    },
     // --- Workflow & Build Tools ---
     {
         name: 'coursecode_workflow_status',
@@ -652,7 +689,7 @@ function buildBrowserRules() {
     return `## Browser Architecture (CRITICAL)
 
 The MCP server runs its OWN headless Chrome internally via puppeteer-core.
-All runtime tools (state, navigate, interact, screenshot, reset) execute instantly inside this headless browser.
+All runtime tools (state, navigate, interact, screenshot, viewport, reset) execute instantly inside this headless browser.
 
 ### Preview Server Ownership
 - The MCP does NOT start or manage the preview server
@@ -663,7 +700,8 @@ All runtime tools (state, navigate, interact, screenshot, reset) execute instant
 ### Navigation API
 - coursecode_state → get slim TOC with slide IDs, current slide, interactions, engagement, lmsState, apiLog, errors, frameworkLogs, consoleLogs
 - coursecode_navigate(slideId) → go to any slide instantly by ID
-- coursecode_screenshot(slideId) → navigate + capture in one call
+- coursecode_viewport(breakpoint or {width,height}) → set viewport for responsive testing (persists until changed)
+- coursecode_screenshot(slideId) → navigate + capture in one call (quality modes only, never changes viewport)
 - coursecode_interact(interactionId, response) → set response + evaluate in one call
 - NEVER click nav buttons or menu items via browser tools. Use these MCP tools.
 

package/lib/mcp-server.js

@@ -211,6 +211,17 @@ export async function startMcpServer(options = {}) {
                         }]
                     };
 
+                case 'coursecode_viewport':
+                    await ensureHeadless(port);
+                    if (args?.breakpoint) {
+                        result = await headless.setViewport(args.breakpoint);
+                    } else if (args?.width && args?.height) {
+                        result = await headless.setViewport({ width: args.width, height: args.height });
+                    } else {
+                        throw new Error('Provide either a breakpoint name or both width and height.');
+                    }
+                    break;
+
                 // === Workflow & build tools ===
                 case 'coursecode_workflow_status':
                     result = await getWorkflowStatusWithInstructions(port);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "coursecode",
-  "version": "0.1.2",
+  "version": "0.1.5",
   "description": "Multi-format course authoring framework with CLI tools (SCORM 2004, SCORM 1.2, cmi5, LTI 1.3)",
   "type": "module",
   "bin": {