coursecode 0.1.7 → 0.1.9

package/README.md

@@ -1,21 +1,23 @@
 # CourseCode
 
-**AI-first course authoring: create interactive e-learning without writing code, then deploy to any LMS format.**
+**Open-source, local-first course authoring with AI help — no coding required to start, full code control when you need it.**
 
-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.
+CourseCode creates real project files you can inspect, version, and edit directly — with a predictable, file-based workflow instead of a black-box GUI.
+
+Bring your own PDFs, Word docs, or PowerPoints, use AI to accelerate authoring, and deploy to any LMS format without vendor lock-in or subscriptions.
 
 ## Start Here
 
-If you're creating courses (non-technical or technical), use the **[User Guide](framework/docs/USER_GUIDE.md)** as your primary documentation.
+Start with the workflow that fits you:
 
-- **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
+- **Course authors (prefer buttons and guided setup):** Start with **[CourseCode Desktop](https://coursecodedesktop.com)** if you want the easiest path and do not want to deal with Node.js or terminal setup
+- **Course authors (prefer editing files and running commands):** Start with the **[User Guide](framework/docs/USER_GUIDE.md)** in this repo for the framework workflow
 - **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
+- **No coding required to start**: Describe what you want and let AI help build slides, interactions, and structure
 - **Full LMS integration**: SCORM 1.2, SCORM 2004, cmi5, and LTI with complete tracking records
 - **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
@@ -26,13 +28,17 @@ If you're creating courses (non-technical or technical), use the **[User Guide](
 - **Themeable design**: CSS custom properties for easy brand customization
 - **Custom endpoints**: Optional webhooks for error reporting and learning record storage
 - **Live preview**: Visual editing, status dashboard, config panels, catalog browser, and full LMS simulation with debug tools
-- **[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
+- **[CourseCode Cloud](https://coursecodecloud.com)**: Deploy from CLI, share preview links, download any LMS format on demand — no rebuilds
+- **[CourseCode Desktop](https://coursecodedesktop.com)**: Native app for Mac and Windows with AI-assisted editing and built-in preview
 
 ---
 
 ## Installation
 
+This section is for the **CourseCode Framework CLI** (file-based workflow using Node.js and terminal commands).
+
+If you want the easiest setup with buttons and guided steps, use **[CourseCode Desktop](https://coursecodedesktop.com)** instead.
+
 ### Required
 
 Install [Node.js](https://nodejs.org/) (v18 or later), then run:
@@ -65,7 +71,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?** Start with the [User Guide](framework/docs/USER_GUIDE.md). It is the primary guide for both non-technical and technical course authors.
+**New to CourseCode?** If you want the easiest setup, start with **[CourseCode Desktop](https://coursecodedesktop.com)**. If you're using the framework CLI, start with the [User Guide](framework/docs/USER_GUIDE.md).
 
 ---
 
@@ -179,7 +185,7 @@ The preview server provides:
 
 When ready, deploy:
 
-**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.
+**With [CourseCode Cloud](https://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
@@ -218,7 +224,7 @@ For the full command list and deployment options, see the [User Guide](framework
 
 ## UI Components
 
-Build engaging slides with interactive elements. No coding required — your AI assistant handles the implementation.
+Build engaging slides with interactive elements. Start with AI assistance, then edit the generated files directly whenever you want more control.
 
 ### Media & Widgets
 

package/bin/cli.js

@@ -20,6 +20,33 @@ import { fileURLToPath } from 'url';
 import path from 'path';
 import fs from 'fs';
 
+// =============================================================================
+// CORPORATE NETWORK: System CA cert auto-injection
+//
+// On corporate machines with SSL-inspecting proxies (e.g. Zscaler), the proxy
+// presents its own CA certificate. Node.js ships its own CA bundle and ignores
+// the OS trust store, so TLS verification fails.
+//
+// Fix: export the OS root cert store to a temp PEM file and re-exec with
+// NODE_EXTRA_CA_CERTS pointing to it. Node picks it up before any TLS
+// handshakes. Transparent to users — completes in < 200ms.
+//
+// The NODE_EXTRA_CA_CERTS guard prevents an infinite re-exec loop.
+// =============================================================================
+
+if (!process.env.NODE_EXTRA_CA_CERTS) {
+  const { exportSystemCerts } = await import('../lib/cloud-certs.js');
+  const certPath = await exportSystemCerts();
+  if (certPath) {
+    const { execFileSync } = await import('child_process');
+    execFileSync(process.execPath, process.argv.slice(1), {
+      env: { ...process.env, NODE_EXTRA_CA_CERTS: certPath },
+      stdio: 'inherit',
+    });
+    process.exit(0);
+  }
+}
+
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const packageJson = JSON.parse(fs.readFileSync(path.join(__dirname, '..', 'package.json'), 'utf-8'));
 
@@ -200,7 +227,6 @@ program
   .description('Send a test error to verify error reporting is configured correctly')
   .option('-t, --type <type>', 'Type of test: error or report', 'error')
   .option('-m, --message <message>', 'Custom message to include in the test')
-  .option('--insecure', 'Skip TLS certificate verification (for corporate proxies)')
   .action(async (options) => {
     const { testErrorReporting } = await import('../lib/test-error-reporting.js');
     await testErrorReporting(options);
@@ -212,7 +238,6 @@ program
   .description('Send a test data record to verify data reporting is configured correctly')
   .option('-t, --type <type>', 'Type of record: assessment, objective, or interaction', 'assessment')
   .option('-m, --message <message>', 'Custom message to include in the test')
-  .option('--insecure', 'Skip TLS certificate verification (for corporate proxies)')
   .action(async (options) => {
     const { testDataReporting } = await import('../lib/test-data-reporting.js');
     await testDataReporting(options);
@@ -280,10 +305,11 @@ program
   .command('login')
   .description('Log in to CourseCode Cloud')
   .option('--local', 'Use local Cloud instance (http://localhost:3000)')
+  .option('--json', 'Emit machine-readable JSON (for GUI/desktop integration)')
   .action(async (options) => {
     const { login, setLocalMode } = await import('../lib/cloud.js');
     if (options.local) setLocalMode();
-    await login();
+    await login({ json: options.json });
   });
 
 program

package/framework/css/interactions/interactive-image.css

@@ -61,7 +61,7 @@
 .interactive-image-hotspot[data-color="primary"] { --hotspot-color: var(--color-primary, #14213d); }
 .interactive-image-hotspot[data-color="secondary"] { --hotspot-color: var(--color-secondary, #f18701); }
 .interactive-image-hotspot[data-color="success"] { --hotspot-color: var(--color-success, #1d7648); }
-.interactive-image-hotspot[data-color="danger"] { --hotspot-color: var(--color-danger, #f35b04); }
+.interactive-image-hotspot[data-color="danger"] { --hotspot-color: var(--color-danger, #c7322b); }
 .interactive-image-hotspot[data-color="warning"] { --hotspot-color: var(--color-warning, #f7b801); }
 .interactive-image-hotspot[data-color="info"] { --hotspot-color: var(--color-info, #4a6fa5); }
 .interactive-image-hotspot[data-color="light"] { --hotspot-color: var(--color-gray-50, #fafafa); }
@@ -71,7 +71,7 @@
 .interactive-image-hotspot[data-viewed-color="primary"] { --viewed-color: var(--color-primary, #14213d); }
 .interactive-image-hotspot[data-viewed-color="secondary"] { --viewed-color: var(--color-secondary, #f18701); }
 .interactive-image-hotspot[data-viewed-color="success"] { --viewed-color: var(--color-success, #1d7648); }
-.interactive-image-hotspot[data-viewed-color="danger"] { --viewed-color: var(--color-danger, #f35b04); }
+.interactive-image-hotspot[data-viewed-color="danger"] { --viewed-color: var(--color-danger, #c7322b); }
 .interactive-image-hotspot[data-viewed-color="warning"] { --viewed-color: var(--color-warning, #f7b801); }
 .interactive-image-hotspot[data-viewed-color="info"] { --viewed-color: var(--color-info, #4a6fa5); }
 .interactive-image-hotspot[data-viewed-color="light"] { --viewed-color: var(--color-gray-50, #fafafa); }

package/framework/docs/COURSE_AUTHORING_GUIDE.md

@@ -660,7 +660,7 @@ createLikertQuestion({
 
 ### Custom Interactions
 
-Add a `.js` file to `course/interactions/`. File `rating-scale.js` → factory `CourseCode.createRatingScaleQuestion()`. See `course/interactions/PLUGIN_GUIDE.md`.
+Add a `.js` file to `course/interactions/`. File `rating-scale.js` → factory `CourseCode.createRatingScaleQuestion()`. See "Extending with Plugins" in `framework/docs/USER_GUIDE.md`.
 
 ### Interaction Methods
 
@@ -1688,6 +1688,8 @@ environment: {
 
 Three optional, config-driven tools for outbound communication. Each activates when its `endpoint` is set — no code changes needed.
 
+> **CourseCode Cloud (AI note):** These `environment.*` endpoint settings are the **manual/self-hosted fallback**. On cloud-served launches, CourseCode Cloud injects `cc-*` meta tags into `index.html`, and the framework uses those values instead (override). This is intentional zero-config behavior for cloud error/data/channel wiring.
+
 | Tool | What it sends | Transport | Example backend |
 |------|--------------|-----------|-----------------|
 | **Error Reporter** | Framework errors (`*:error` events) | POST per error (60s dedup) | `cloudflare-error-worker.js` |
@@ -1711,6 +1713,8 @@ eventBus.on('channel:message', (data) => { /* any JSON */ });
 All example backends are in `framework/docs/examples/`.
 
 > **Local dev:** Error and data reporters are automatically disabled during watch builds (`coursecode preview`, `coursecode dev`). Production builds (`coursecode build`) send reports normally.
+>
+> **Cloud precedence:** Cloud-injected meta tags override `course-config.js` endpoint settings for these tools. If you need custom routing/fanout, prefer doing it server-side from your cloud ingestion endpoint.
 
 ---
 

package/framework/docs/FRAMEWORK_GUIDE.md

@@ -1122,7 +1122,7 @@ Exposed globally via `CourseCode.breakpointManager`.
 
 ## Adding New Interaction Types
 
-> **Course Authors:** See `course/interactions/PLUGIN_GUIDE.md`. Steps below are for framework developers.
+> **Course Authors:** See "Extending with Plugins" in `framework/docs/USER_GUIDE.md`. Steps below are for framework developers.
 
 1. Create file in `framework/js/components/interactions/`
 2. Export `create(container, config)`, `metadata`, and `schema`

package/framework/docs/USER_GUIDE.md

@@ -43,7 +43,12 @@ A complete guide to creating interactive e-learning courses with AI assistance.
    - [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)
+8. [Extending with Plugins](#extending-with-plugins)
+   - [Custom Interactions](#custom-interactions)
+   - [Custom UI Components](#custom-ui-components)
+   - [Custom Icons](#custom-icons)
+   - [Custom Styles](#custom-styles)
+9. [Sharing and Deploying](#sharing-and-deploying)
    - [Sharing Previews](#sharing-previews)
    - [Preview Export Options](#preview-export-options)
    - [Understanding LMS Formats](#understanding-lms-formats)
@@ -51,8 +56,8 @@ A complete guide to creating interactive e-learning courses with AI assistance.
    - [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)
+10. [Generating Audio Narration](#generating-audio-narration)
+11. [Troubleshooting](#troubleshooting)
 
 ---
 
@@ -514,6 +519,93 @@ Best practice: set and increment `metadata.version` in `course/course-config.js`
 
 ---
 
+## Extending with Plugins
+
+CourseCode has a built-in plugin system. You can extend it with your own interaction types, UI components, icons, and styles — all auto-discovered from your `course/` folder without any framework changes.
+
+| Extension Point | Where to Put It | What It Adds |
+|-----------------|-----------------|-------------|
+| Custom interactions | `course/interactions/*.js` | New question/activity types |
+| Custom UI components | `course/components/*.js` | New reusable HTML components |
+| Custom icons | `course/icons.js` | New icons available everywhere |
+| Custom styles | `course/theme.css` | Global CSS for your plugins and brand |
+
+Plugins are just JavaScript files that follow a simple contract. Your AI assistant can write them — describe what you want and share `framework/docs/USER_GUIDE.md` (see "Extending with Plugins") as context.
+
+### Custom Interactions
+
+Create a new question or activity type by dropping a `.js` file in `course/interactions/`. It registers automatically.
+
+A minimal plugin exports one function:
+
+```javascript
+// course/interactions/rating-scale.js
+export function create(container, config) {
+  let response = null;
+  container.innerHTML = `<div data-interaction-id="${config.id}">...</div>`;
+  return {
+    getResponse: () => response,
+    setResponse: (val) => { response = val; },
+    checkAnswer: () => ({ correct: response === config.correctAnswer, score: 1 }),
+    reset: () => { response = null; }
+  };
+}
+```
+
+Then use it in a slide:
+
+```javascript
+const rating = CourseCode.createRatingScaleQuestion(container, {
+  id: 'my-rating',
+  prompt: 'How would you rate this?',
+  options: ['Poor', 'Fair', 'Good', 'Excellent']
+});
+```
+
+The factory name is derived from the filename: `rating-scale.js` → `createRatingScaleQuestion`.
+
+For a complete example with schema and metadata (which enable linting and AI tooling), see the "Extending with Plugins" section in `framework/docs/USER_GUIDE.md`.
+
+### Custom UI Components
+
+Add reusable HTML components (info boxes, custom cards, branded banners) by dropping a `.js` file in `course/components/`. Use them in slides via `data-component`:
+
+```html
+<div data-component="info-box" data-icon="warning">
+  Important note here
+</div>
+```
+
+See the "Extending with Plugins" section in `framework/docs/USER_GUIDE.md` for the component contract.
+
+### Custom Icons
+
+Add icons to `course/icons.js` and they're available throughout the course:
+
+```javascript
+// course/icons.js
+export const customIcons = {
+  'rocket': '<path d="M12 2L8 8H4l8 14 8-14h-4L12 2z" />'
+};
+```
+
+### Custom Styles
+
+`course/theme.css` is always loaded. It's the right place for plugin-specific CSS as well as brand colors and fonts:
+
+```css
+/* course/theme.css */
+:root {
+  --primary: #0066cc;
+}
+
+.info-box { border-left: 4px solid var(--primary); padding: 1rem; }
+```
+
+Use CSS variables from the design system (`--primary`, `--border`, `--radius`, etc.) so your plugins automatically respect the course theme.
+
+---
+
 ## Sharing and Deploying
 
 ### Sharing Previews
@@ -605,11 +697,54 @@ coursecode build --format scorm1.2-proxy
 CourseCode Cloud is the simplest deployment option. Upload your course once and the cloud handles everything:
 
 ```bash
+coursecode login     # First time only: sign in to CourseCode Cloud
 coursecode deploy    # Build + upload to cloud
 ```
 
 **How it works:** Your course is built once as a universal package. The cloud can generate a format-specific ZIP (SCORM 1.2, SCORM 2004, cmi5, etc.) on demand — no rebuilding required. You never need to set a format in `course-config.js` for cloud-deployed courses.
 
+Cloud-served launches also auto-configure runtime error reporting, data reporting, and channel relay endpoints (zero-config cloud wiring).
+If you configured manual endpoints in `course-config.js` for self-hosted workflows, Cloud launches override them with cloud-injected runtime config.
+
+**Signing in (`coursecode login`):**
+
+Running `coursecode login` displays a URL and a short code in your terminal:
+
+```
+  ┌─────────────────────────────────────────────────────┐
+  │  Open this URL in your browser:                     │
+  │  https://coursecodecloud.com/activate               │
+  │                                                     │
+  │  Enter your code:  ABCD-1234                        │
+  │                                                     │
+  │  Expires in 15 minutes                              │
+  └─────────────────────────────────────────────────────┘
+```
+
+Open the URL in any browser, log in with your CourseCode account, and enter the code. The terminal confirms login automatically — no redirect back required. The code is valid for 15 minutes and works from any device or browser.
+
+**What CourseCode Cloud helps with (plain English):**
+- Host your course online so learners/reviewers can access it without you manually hosting files
+- Generate the LMS package you need later (SCORM/cmi5) from the same upload
+- Share preview links for stakeholder review
+- Manage deployment updates without rebuilding separate packages for each LMS format
+- Provide cloud-managed runtime services (reporting/channel) without extra endpoint setup in your course files
+
+**Typical Cloud workflow:**
+1. Run `coursecode login` once, open the URL shown, and enter the code.
+2. Run `coursecode deploy` from your project folder.
+3. Open the CourseCode Cloud dashboard link shown after deploy.
+4. Use Cloud preview links for review.
+5. Download the LMS format you need from Cloud when you're ready to deliver.
+
+**Prefer a GUI instead of the terminal?**
+- Use **CourseCode Desktop** for the same project workflow with buttons for Preview / Export / Deploy.
+- Desktop docs: `coursecode-desktop/USER_GUIDE.md`
+
+**When to use Cloud vs local export:**
+- Use **local export** if you just need a ZIP to upload manually and don't need hosted previews or cloud services.
+- Use **Cloud** if you want easier sharing, hosted delivery workflows, or format downloads later without rebuilding.
+
 **Benefits:**
 - **No format decisions** — download the right ZIP for any LMS directly from the cloud
 - **Instant updates** — redeploy and all future launches get the new version

package/framework/docs/examples/cloudflare-channel-relay.js

@@ -3,6 +3,9 @@
  * 
  * Content-agnostic message fan-out. Receives JSON via POST, broadcasts to all
  * connected SSE clients on the same channel. Does not parse or interpret messages.
+ * Self-hosted/manual relay example: on CourseCode Cloud, runtime channel endpoint/id are injected
+ * by the platform and override course-config.js endpoint values.
+ * Use this either for self-hosted relay infrastructure, or as a cloud-managed relay implementation/reference.
  * 
  * SETUP:
  * 1. Create a Cloudflare account and go to Workers & Pages

package/framework/docs/examples/cloudflare-data-worker.js

@@ -3,6 +3,9 @@
  * 
  * Receives batched learning records (assessments, objectives, interactions) 
  * from courses and stores them for analytics or forwards to your data warehouse.
+ * Self-hosted/manual endpoint example: on CourseCode Cloud, runtime endpoints/API key are injected
+ * by the platform and override course-config.js endpoint values.
+ * Use this either for self-hosted telemetry, or as a downstream target if Cloud fans out records server-side.
  * 
  * SETUP:
  * 1. Create a Cloudflare account and go to Workers & Pages

package/framework/docs/examples/cloudflare-error-worker.js

@@ -3,6 +3,9 @@
  * 
  * Deploy this worker to receive error reports and user issue reports from courses
  * and send email alerts. The API key stays server-side, so it's never exposed in the course.
+ * Self-hosted/manual endpoint example: on CourseCode Cloud, runtime endpoints/API key are injected
+ * by the platform and override course-config.js endpoint values.
+ * Use this either for self-hosted telemetry, or as a downstream target if Cloud fans out reports server-side.
  * 
  * SETUP:
  * 1. Create a Cloudflare account and go to Workers & Pages

package/lib/cloud-certs.js

@@ -0,0 +1,141 @@
+/**
+ * cloud-certs.js — System CA certificate export for corporate network compatibility.
+ *
+ * Exports the OS trusted root store to a temp PEM file so Node.js can verify
+ * TLS connections that pass through SSL-inspecting proxies (e.g. Zscaler).
+ *
+ * Returns the path to the PEM file on success, null on failure.
+ * Never throws — silent fallback for non-corporate machines.
+ */
+
+import { execFile } from 'child_process';
+import { promisify } from 'util';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import crypto from 'crypto';
+
+const execFileAsync = promisify(execFile);
+
+/** Cached result — only export once per process lifetime. */
+let _cachedCertPath = undefined;
+
+/**
+ * Export the OS system root certificate store to a temp PEM file.
+ *
+ * @returns {Promise<string|null>} Absolute path to the PEM file, or null if unavailable.
+ */
+export async function exportSystemCerts() {
+  if (_cachedCertPath !== undefined) return _cachedCertPath;
+
+  try {
+    const pem = await readSystemCerts();
+    if (!pem || !pem.trim()) {
+      _cachedCertPath = null;
+      return null;
+    }
+
+    // Write to a stable temp path (same content = same hash, avoids accumulation)
+    const hash = crypto.createHash('sha1').update(pem).digest('hex').slice(0, 8);
+    const certPath = path.join(os.tmpdir(), `coursecode-ca-${hash}.pem`);
+
+    if (!fs.existsSync(certPath)) {
+      fs.writeFileSync(certPath, pem, { mode: 0o600 });
+    }
+
+    _cachedCertPath = certPath;
+    return certPath;
+  } catch {
+    _cachedCertPath = null;
+    return null;
+  }
+}
+
+/**
+ * Read system certificates as a PEM string.
+ * Platform-specific — returns null if the platform is unsupported or export fails.
+ */
+async function readSystemCerts() {
+  const platform = process.platform;
+
+  if (platform === 'darwin') {
+    return readMacosCerts();
+  }
+
+  if (platform === 'win32') {
+    return readWindowsCerts();
+  }
+
+  // Linux/other: read well-known bundle paths directly
+  return readLinuxCerts();
+}
+
+/**
+ * macOS: export the system root keychain via the `security` CLI tool.
+ * This includes all roots installed via Apple MDM / System Preferences.
+ */
+async function readMacosCerts() {
+  // Export from all common keychains — ignore errors on missing keychains
+  const keychains = [
+    '/Library/Keychains/SystemRootCertificates.keychain',
+    '/System/Library/Keychains/SystemRootCertificates.keychain',
+    '/Library/Keychains/System.keychain',
+  ];
+
+  const pems = [];
+  for (const keychain of keychains) {
+    try {
+      const { stdout } = await execFileAsync('security', [
+        'find-certificate', '-a', '-p', keychain,
+      ], { maxBuffer: 16 * 1024 * 1024 });
+      if (stdout) pems.push(stdout);
+    } catch {
+      // Keychain not present on this OS version — skip
+    }
+  }
+
+  return pems.join('\n');
+}
+
+/**
+ * Windows: export LocalMachine\Root via PowerShell.
+ * This includes certs deployed via Group Policy / MDM.
+ */
+async function readWindowsCerts() {
+  const script = [
+    '$certs = Get-ChildItem -Path Cert:\\LocalMachine\\Root',
+    '$pems = $certs | ForEach-Object {',
+    '  $bytes = $_.Export([System.Security.Cryptography.X509Certificates.X509ContentType]::Cert)',
+    '  $b64 = [System.Convert]::ToBase64String($bytes, "InsertLineBreaks")',
+    '  "-----BEGIN CERTIFICATE-----`n" + $b64 + "`n-----END CERTIFICATE-----"',
+    '}',
+    '$pems -join "`n"',
+  ].join('; ');
+
+  const { stdout } = await execFileAsync('powershell', [
+    '-NoProfile', '-NonInteractive', '-Command', script,
+  ], { maxBuffer: 16 * 1024 * 1024 });
+
+  return stdout;
+}
+
+/**
+ * Linux: read the system CA bundle from well-known locations.
+ * No subprocess needed — just read the file directly.
+ */
+function readLinuxCerts() {
+  const candidatePaths = [
+    '/etc/ssl/certs/ca-certificates.crt',       // Debian/Ubuntu
+    '/etc/pki/tls/certs/ca-bundle.crt',          // RHEL/CentOS/Fedora
+    '/etc/ssl/ca-bundle.pem',                     // OpenSUSE
+    '/etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem', // RHEL 7+
+  ];
+
+  for (const p of candidatePaths) {
+    if (fs.existsSync(p)) {
+      return fs.readFileSync(p, 'utf-8');
+    }
+  }
+
+  return null;
+}

package/lib/cloud.js

@@ -22,7 +22,11 @@ const packageJson = JSON.parse(fs.readFileSync(path.join(__dirname, '..', 'packa
 // CONSTANTS
 // =============================================================================
 
-const DEFAULT_CLOUD_URL = 'https://www.coursecodecloud.com';
+const DEFAULT_CLOUD_URL = 'https://coursecodecloud.com';
+// Fallback URL used automatically when the primary domain is blocked by a
+// corporate web filter (e.g. Zscaler URL categorization). *.vercel.app is
+// in a trusted platform category and is unlikely to be categorized as unknown.
+const FALLBACK_CLOUD_URL = 'https://coursecode-cloud-web.vercel.app';
 const LOCAL_CLOUD_URL = 'http://localhost:3000';
 let useLocal = false;
 const CREDENTIALS_DIR = path.join(os.homedir(), '.coursecode');
@@ -31,8 +35,9 @@ const PROJECT_CONFIG_DIR = '.coursecode';
 const PROJECT_CONFIG_PATH = path.join(PROJECT_CONFIG_DIR, 'project.json');
 
 const POLL_INTERVAL_MS = 2000;
-const POLL_TIMEOUT_MS = 5 * 60 * 1000; // 5 minutes
+const POLL_TIMEOUT_MS = 15 * 60 * 1000; // 15 minutes (device code expiry)
 const USER_AGENT = `coursecode-cli/${packageJson.version}`;
+const ACTIVATION_PATH = '/activate';
 
 // =============================================================================
 // SLUG UTILITIES
@@ -163,38 +168,123 @@ function writeRcCloudId(cloudId) {
  * Make an authenticated request to the Cloud API.
  * Handles User-Agent, Bearer token, and error formatting per §7.
  *
+ * Automatically retries against FALLBACK_CLOUD_URL when the primary URL
+ * returns an HTML block page (corporate web filter / Zscaler URL categorization).
+ *
  * @param {string} urlPath - API path (e.g. '/api/cli/whoami')
  * @param {object} options - fetch options (method, body, headers, etc.)
  * @param {string} [token] - Override token (for unauthenticated requests)
- * @returns {Promise<Response>}
+ * @returns {Promise<Response>} A Response whose body has been replaced with
+ *   the raw text so handleResponse can always call res.text() safely.
  */
 async function cloudFetch(urlPath, options = {}, token = null) {
-  const cloudUrl = getCloudUrl();
-  const url = `${cloudUrl}${urlPath}`;
-
   const headers = {
     'User-Agent': USER_AGENT,
     ...options.headers,
   };
+  if (token) headers['Authorization'] = `Bearer ${token}`;
+
+  const attemptFetch = async (baseUrl) => {
+    const url = `${baseUrl}${urlPath}`;
+    try {
+      return await fetch(url, { ...options, headers });
+    } catch {
+      return null; // Connection failed
+    }
+  };
 
-  if (token) {
-    headers['Authorization'] = `Bearer ${token}`;
-  }
+  const primaryUrl = getCloudUrl();
+  const res = await attemptFetch(primaryUrl);
 
-  try {
-    return await fetch(url, { ...options, headers });
-  } catch (_error) {
+  if (!res) {
+    // Primary unreachable — try fallback before giving up
+    if (!useLocal) {
+      const fallback = await attemptFetch(FALLBACK_CLOUD_URL);
+      if (fallback) return fallback;
+    }
     console.error('\n❌ Could not connect to CourseCode Cloud. Check your internet connection.\n');
     process.exit(1);
   }
+
+  // Peek at the body: if it's an HTML block page, silently retry on the fallback.
+  // We must buffer the text here since Response bodies can only be read once.
+  const text = await res.text();
+  if (isBlockPage(text) && !useLocal) {
+    const fallbackRes = await attemptFetch(FALLBACK_CLOUD_URL);
+    if (fallbackRes) {
+      const fallbackText = await fallbackRes.text();
+      if (!isBlockPage(fallbackText)) {
+        // Fallback succeeded — return a synthetic Response with the buffered text
+        return syntheticResponse(fallbackText, fallbackRes.status);
+      }
+    }
+    // Both primary and fallback are blocked — surface the error
+    reportBlockPage(text, res);
+    process.exit(1);
+  }
+
+  // Primary response is fine — return a synthetic Response with the buffered text
+  return syntheticResponse(text, res.status);
+}
+
+/** Quick check whether a response body looks like an HTML block page. */
+function isBlockPage(text) {
+  const lower = text.toLowerCase();
+  return lower.includes('<!doctype') || lower.startsWith('<html');
+}
+
+/**
+ * Create a minimal synthetic Response that wraps already-buffered text.
+ * handleResponse always calls res.text() — this keeps the interface uniform.
+ */
+function syntheticResponse(text, status) {
+  return {
+    ok: status >= 200 && status < 300,
+    status,
+    text: () => Promise.resolve(text),
+  };
+}
+
+/**
+ * Print a vendor-specific block page error message.
+ *
+ * @param {string} body - Raw response body text
+ * @param {Response} res - The fetch Response object
+ */
+function reportBlockPage(body, res) {
+  const lower = body.toLowerCase();
+  if (lower.includes('zscaler')) {
+    console.error('\n❌ coursecodecloud.com is blocked by Zscaler on your network.');
+  } else if (lower.includes('forcepoint') || lower.includes('websense')) {
+    console.error('\n❌ coursecodecloud.com is blocked by Forcepoint on your network.');
+  } else if (lower.includes('barracuda')) {
+    console.error('\n❌ coursecodecloud.com is blocked by Barracuda on your network.');
+  } else {
+    console.error(`\n❌ Your network blocked coursecodecloud.com (HTTP ${res.status}).`);
+  }
+  console.error('   Ask your IT team to whitelist: coursecodecloud.com\n');
 }
 
 /**
  * Handle HTTP error responses per §7.
  * Returns the parsed JSON body, or exits on error.
+ *
+ * Reads the body as text first so we can detect non-JSON responses. By the
+ * time this is called, cloudFetch has already handled block page detection
+ * and fallback retry — so text here should always be valid JSON.
  */
 async function handleResponse(res, { retryFn, _isRetry = false } = {}) {
-  if (res.ok) return res.json();
+  const text = await res.text();
+  let body;
+  try {
+    body = JSON.parse(text);
+  } catch {
+    // Should not happen after cloudFetch filtering — treat as server error
+    console.error(`\n❌ Unexpected response from Cloud (HTTP ${res.status}). Try again later.\n`);
+    process.exit(1);
+  }
+
+  if (res.ok) return body;
 
   const status = res.status;
 
@@ -206,10 +296,15 @@ async function handleResponse(res, { retryFn, _isRetry = false } = {}) {
     return retryFn(true);
   }
 
-  // Parse error body
-  let body;
-  try { body = await res.json(); } catch { body = {}; }
-  const message = body.error || `HTTP ${status}`;
+  return handleResponseError(status, body);
+}
+
+/**
+ * Handle a known HTTP error status code with a parsed body.
+ * Exits the process with an appropriate message.
+ */
+function handleResponseError(status, body) {
+  const message = body?.error || `HTTP ${status}`;
 
   if (status === 403 || status === 409) {
     console.error(`\n❌ ${message}\n`);
@@ -260,18 +355,130 @@ function sleep(ms) {
 }
 
 /**
- * Run the nonce exchange login flow.
- * 1. Generate nonce
- * 2. POST /api/auth/connect to create session
- * 3. Open browser
- * 4. Poll until token received or timeout
- * 5. Store credentials
+ * Run the device code login flow (primary).
+ *
+ * Flow:
+ *   1. POST /api/auth/device  → get { deviceCode, userCode, verificationUri, expiresIn, interval }
+ *   2. Display userCode + activation URLs prominently
+ *   3. Open browser as a convenience (user can ignore if ZBI isolates it)
+ *   4. Poll GET /api/auth/device?code={deviceCode} until token or expiry
+ *   5. Store credentials
+ *
+ * Resilient to Zscaler Browser Isolation: the browser session is fully decoupled
+ * from the CLI. The user can open the activation URL in any browser, on any device.
+ *
+ * Falls back to the legacy nonce flow if the cloud returns 404 (not yet deployed).
+ */
+async function runLoginFlow({ jsonMode = false } = {}) {
+  // Helper: emit a JSON event line (JSON mode) or nothing (normal mode)
+  const emit = (obj) => process.stdout.write(JSON.stringify(obj) + '\n');
+  const log = (...args) => { if (!jsonMode) console.log(...args); };
+
+  // Step 1: Request device code
+  const deviceRes = await cloudFetch('/api/auth/device', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+  });
+
+  // Graceful fallback: cloud not yet updated to support device flow
+  if (deviceRes.status === 404) {
+    return runLegacyLoginFlow();
+  }
+
+  if (!deviceRes.ok) {
+    let body = {};
+    try { body = JSON.parse(await deviceRes.text()); } catch { /* ignore */ }
+    const msg = body.error || `HTTP ${deviceRes.status}`;
+    if (jsonMode) { emit({ type: 'error', error: msg }); } else { console.error(`\n❌ Failed to start login: ${msg}\n`); }
+    process.exit(1);
+  }
+
+  let devicePayload;
+  try {
+    devicePayload = JSON.parse(await deviceRes.text());
+  } catch {
+    console.error('\n❌ Unexpected response from Cloud during login. Try again.\n');
+    process.exit(1);
+  }
+  const { deviceCode, userCode, verificationUri, expiresIn, interval } = devicePayload;
+
+  const pollIntervalMs = (interval || 5) * 1000;
+  const expiryMs = (expiresIn || 900) * 1000;
+
+  // Derive the activation URL from the server response or fall back to the primary domain
+  const primaryActivationUrl = verificationUri || `${getCloudUrl()}${ACTIVATION_PATH}`;
+
+  if (jsonMode) {
+    // Emit structured event for GUI to display its own device code UI
+    emit({
+      type: 'device_code',
+      userCode,
+      verificationUri: primaryActivationUrl,
+      deviceCode,
+      expiresIn: expiresIn || 900,
+      interval: interval || 5,
+    });
+  } else {
+    // Step 2: Display code prominently
+    const line = '─'.repeat(51);
+    log(`\n  ┌${line}┐`);
+    log('  │  Open this URL in your browser:                   │');
+    log(`  │  ${primaryActivationUrl.padEnd(49)}│`);
+    log('  │                                                   │');
+    log(`  │  Enter your code:  ${userCode.padEnd(31)}│`);
+    log('  │                                                   │');
+    const expiryMins = Math.round(expiryMs / 60000);
+    log(`  │  Expires in ${String(expiryMins + ' minutes').padEnd(37)}│`);
+    log(`  └${line}┘\n`);
+  }
+
+  // Step 3: Poll for token
+  log('  Waiting for authorization...');
+  const startTime = Date.now();
+  while (Date.now() - startTime < expiryMs) {
+    await sleep(pollIntervalMs);
+
+    const pollRes = await cloudFetch(`/api/auth/device?code=${encodeURIComponent(deviceCode)}`);
+
+    if (pollRes.status === 410) {
+      const msg = 'Login code expired. Run `coursecode login` to try again.';
+      if (jsonMode) { emit({ type: 'error', error: 'expired' }); } else { console.error(`\n❌ ${msg}\n`); }
+      process.exit(1);
+    }
+
+    if (pollRes.status === 400) {
+      let body = {};
+      try { body = JSON.parse(await pollRes.text()); } catch { /* ignore */ }
+      if (jsonMode) { emit({ type: 'error', error: body.error || 'denied' }); } else { console.error(`\n❌ Login ${body.error || 'failed'}. Run \`coursecode login\` to try again.\n`); }
+      process.exit(1);
+    }
+
+    if (!pollRes.ok) continue;
+
+    const data = JSON.parse(await pollRes.text());
+    if (data.pending) continue;
+
+    if (data.token) {
+      writeCredentials(data.token, getCloudUrl());
+      log('  ✓ Logged in successfully\n');
+      return data.token;
+    }
+  }
+
+  const timeoutMsg = 'Login timed out. Run `coursecode login` to try again.';
+  if (jsonMode) { emit({ type: 'error', error: 'timeout' }); } else { console.error(`\n❌ ${timeoutMsg}\n`); }
+  process.exit(1);
+}
+
+/**
+ * Legacy nonce-exchange login flow.
+ * Used as a fallback when the cloud has not yet deployed the device code endpoint.
+ * Can be removed once the device code flow is fully rolled out.
  */
-async function runLoginFlow() {
+async function runLegacyLoginFlow() {
   const nonce = crypto.randomBytes(32).toString('hex');
   const cloudUrl = getCloudUrl();
 
-  // Step 1: Create CLI session
   console.log('  → Registering session...');
   const createRes = await cloudFetch('/api/auth/connect', {
     method: 'POST',
@@ -280,17 +487,16 @@ async function runLoginFlow() {
   });
 
   if (!createRes.ok) {
-    const body = await createRes.json().catch(() => ({}));
+    let body = {};
+    try { body = JSON.parse(await createRes.text()); } catch { /* ignore */ }
     console.error(`\n❌ Failed to start login: ${body.error || `HTTP ${createRes.status}`}\n`);
     process.exit(1);
   }
 
-  // Step 2: Open browser
   const loginUrl = `${cloudUrl}/auth/connect?session=${nonce}`;
   console.log('  → Opening browser for authentication...');
   openBrowser(loginUrl);
 
-  // Step 3: Poll for token
   const startTime = Date.now();
   while (Date.now() - startTime < POLL_TIMEOUT_MS) {
     await sleep(POLL_INTERVAL_MS);
@@ -304,7 +510,7 @@ async function runLoginFlow() {
 
     if (!pollRes.ok) continue;
 
-    const data = await pollRes.json();
+    const data = JSON.parse(await pollRes.text());
     if (data.pending) continue;
 
     if (data.token) {
@@ -446,21 +652,26 @@ function formatDate(isoString) {
 /**
  * coursecode login — explicit (re-)authentication
  */
-export async function login() {
-  console.log('\n🔑 Logging in to CourseCode Cloud...\n');
-  await runLoginFlow();
+export async function login(options = {}) {
+  const jsonMode = Boolean(options.json);
+  if (!jsonMode) console.log('\n🔑 Logging in to CourseCode Cloud...\n');
+  await runLoginFlow({ jsonMode });
 
   // Show who they are
   const token = readCredentials()?.token;
   if (token) {
     const res = await cloudFetch('/api/cli/whoami', {}, token);
     if (res.ok) {
-      const data = await res.json();
-      console.log(`  ✓ Logged in as ${data.full_name} (${data.email})\n`);
+      const data = JSON.parse(await res.text());
+      if (jsonMode) {
+        process.stdout.write(JSON.stringify({ type: 'success', email: data.email, name: data.full_name }) + '\n');
+      } else {
+        console.log(`  ✓ Logged in as ${data.full_name} (${data.email})\n`);
+      }
       return;
     }
   }
-  console.log('');
+  if (!jsonMode) console.log('');
 }
 
 /**

package/lib/mcp-prompts.js

@@ -715,7 +715,7 @@ All runtime tools (state, navigate, interact, screenshot, viewport, reset) execu
 ### Customization (all in course/, never in framework/)
 - **CSS overrides**: Edit \`course/theme.css\` — override palette tokens to rebrand (all colors cascade via color-mix). Use framework utility classes first (\`coursecode_css_catalog\`), \`theme.css\` only for brand-specific overrides.
 - **Custom components**: Add \`.js\` files to \`course/components/\` — auto-discovered at build time. Use \`coursecode_component_catalog\` for built-in options first.
-- **Custom interactions**: Add \`.js\` files to \`course/interactions/\` — auto-discovered. See \`course/interactions/PLUGIN_GUIDE.md\` for the template.
+- **Custom interactions**: Add \`.js\` files to \`course/interactions/\` — auto-discovered. See "Extending with Plugins" in \`framework/docs/USER_GUIDE.md\` for the contract.
 - **Custom icons**: Add SVG definitions to \`course/icons.js\` — merged with built-in icons. Use icon_catalog to check existing icons first.`;
 }
 

package/lib/stub-player/styles/_base.css

@@ -25,7 +25,7 @@
             --color-warning-bright: color-mix(in srgb, var(--color-warning) 70%, var(--color-accent));
             --color-accent: #f7b801;
 
-            --color-danger: #f35b04;
+            --color-danger: #c7322b;
             --color-danger-soft: color-mix(in srgb, var(--color-danger) 55%, var(--color-white));
             --color-black: #000;
 

package/lib/test-data-reporting.js

@@ -15,11 +15,6 @@ import { pathToFileURL } from 'url';
  * @param {string} options.message - Custom message to include
  */
 export async function testDataReporting(options = {}) {
-    // Handle TLS certificate issues (corporate proxies)
-    if (options.insecure) {
-        process.env.NODE_TLS_REJECT_UNAUTHORIZED = '0';
-    }
-
     const cwd = process.cwd();
     const configPath = path.join(cwd, 'course', 'course-config.js');
 

package/lib/test-error-reporting.js

@@ -15,11 +15,6 @@ import { pathToFileURL } from 'url';
  * @param {string} options.message - Custom message to include
  */
 export async function testErrorReporting(options = {}) {
-    // Handle TLS certificate issues (corporate proxies)
-    if (options.insecure) {
-        process.env.NODE_TLS_REJECT_UNAUTHORIZED = '0';
-    }
-    
     const cwd = process.cwd();
     const configPath = path.join(cwd, 'course', 'course-config.js');
     

package/package.json

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

package/template/course/components/components-readme.md

@@ -0,0 +1,5 @@
+# Custom Components
+
+Drop `.js` files here to add new UI components. They are auto-discovered and registered at build time.
+
+See **"Extending with Plugins"** in `framework/docs/USER_GUIDE.md` for the plugin contract and examples.

package/template/course/course-config.js

@@ -70,6 +70,8 @@
  *   Sends framework errors to a webhook for email alerts. Disabled if endpoint is missing.
  *   enableUserReports adds "Report Issue" button to settings menu (default: true when endpoint set).
  *   Use with Cloudflare Worker to keep API keys server-side.
+ *   CourseCode Cloud launches override manual endpoint config via injected <meta name="cc-*"> tags
+ *   (zero-config cloud wiring). Treat this as a self-hosted/manual fallback.
  *
  * LMS COMPATIBILITY PROFILE (environment.lmsCompatibilityMode):
  *   'auto' (default): choose profile by format (strict-scorm12 / conservative-scorm2004 / modern-http)

package/template/course/interactions/interactions-readme.md

@@ -0,0 +1,5 @@
+# Custom Interactions
+
+Drop `.js` files here to add new interaction types. They are auto-discovered and registered at build time.
+
+See **"Extending with Plugins"** in `framework/docs/USER_GUIDE.md` for the plugin contract and examples.

package/template/course/interactions/PLUGIN_GUIDE.md

@@ -1,97 +0,0 @@
-# Custom Interactions
-
-Drop a `.js` file here to auto-register a custom interaction type.
-
-## Quick Start
-
-**File:** `rating-scale.js` → **Factory:** `CourseCode.createRatingScaleQuestion()`
-
-```javascript
-// Optional: Schema for linting/AI assistance
-export const schema = {
-  type: 'rating-scale',
-  properties: {
-    options: { type: 'array', required: true, description: 'Rating options' },
-    correctAnswer: { type: 'string', description: 'Correct option index' }
-  }
-};
-
-// Optional: Metadata for UI tools
-export const metadata = {
-  label: 'Rating Scale',
-  category: 'interactive',
-  scormType: 'choice'
-};
-
-// Required: Creator function
-export function create(container, config) {
-  let response = null;
-  
-  // Inject styles once
-  if (!document.getElementById('rating-scale-styles')) {
-    const el = document.createElement('style');
-    el.id = 'rating-scale-styles';
-    el.textContent = `
-      .rating-scale { display: flex; gap: 0.5rem; }
-      .rating-scale-option { cursor: pointer; padding: 0.5rem 1rem; border: 1px solid var(--border); border-radius: var(--radius); }
-      .rating-scale-option.selected { background: var(--primary); color: white; }
-    `;
-    document.head.appendChild(el);
-  }
-  
-  container.innerHTML = `
-    <div class="interaction" data-interaction-id="${config.id}">
-      <p class="prompt">${config.prompt}</p>
-      <div class="rating-scale">
-        ${config.options.map((opt, i) => 
-          `<button type="button" class="rating-scale-option" data-value="${i}">${opt}</button>`
-        ).join('')}
-      </div>
-    </div>
-  `;
-  
-  container.querySelectorAll('.rating-scale-option').forEach(btn => {
-    btn.addEventListener('click', () => {
-      container.querySelectorAll('.rating-scale-option').forEach(b => b.classList.remove('selected'));
-      btn.classList.add('selected');
-      response = btn.dataset.value;
-    });
-  });
-  
-  return {
-    getResponse: () => response,
-    setResponse: (val) => {
-      response = val;
-      container.querySelectorAll('.rating-scale-option').forEach(btn => {
-        btn.classList.toggle('selected', btn.dataset.value === String(val));
-      });
-    },
-    checkAnswer: () => ({ correct: response === config.correctAnswer, score: response === config.correctAnswer ? 1 : 0 }),
-    reset: () => {
-      response = null;
-      container.querySelectorAll('.rating-scale-option').forEach(b => b.classList.remove('selected'));
-    }
-  };
-}
-```
-
-## Exports
-
-| Export | Required | Purpose |
-|--------|----------|---------|
-| `create(container, config)` | ✅ | Factory function |
-| `schema` | Optional | Enables linting, AI assistance, preview editor |
-| `metadata` | Optional | UI labels, categories, SCORM interaction type |
-
-## Usage in Slides
-
-```javascript
-const rating = CourseCode.createRatingScaleQuestion(container, {
-  id: 'my-rating',
-  prompt: 'How would you rate this?',
-  options: ['Poor', 'Fair', 'Good', 'Excellent'],
-  correctAnswer: '3'
-});
-```
-
-See `COURSE_AUTHORING_GUIDE.md` for full interaction API.