coursecode 0.1.44 → 0.1.47

package/README.md

@@ -175,12 +175,27 @@ The preview server provides:
 
 When ready, deploy:
 
-**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.
+**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 a shareable preview link with optional password protection. No ZIP files, no manual uploads.
 
 ```bash
 coursecode deploy
 ```
 
+For stakeholder review, deploy a preview-only version and password-protect the preview link:
+
+```bash
+coursecode deploy --preview --password
+```
+
+You can inspect recent deployments and move pointers without rebuilding:
+
+```bash
+coursecode deployments
+coursecode promote --preview
+coursecode promote --production
+coursecode preview-link --password
+```
+
 If the cloud course was deleted but the project still has the old local binding, redeploy with:
 
 ```bash
@@ -212,6 +227,9 @@ coursecode preview --export
 | `coursecode lint` | Validate course structure and content |
 | `coursecode build` | Build a package for LMS upload |
 | `coursecode deploy` | Build and deploy to CourseCode Cloud |
+| `coursecode deployments` | List recent Cloud deployments |
+| `coursecode promote` | Move the Production or Preview pointer |
+| `coursecode preview-link` | Manage the Cloud preview link |
 | `coursecode narration` | Generate audio narration from text |
 
 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

@@ -365,7 +365,7 @@ program
   .option('--promote', 'Force-promote: always move production pointer regardless of deploy_mode setting. Mutually exclusive with --stage.')
   .option('--stage', 'Force-stage: never move production pointer regardless of deploy_mode setting. Mutually exclusive with --promote.')
   .option('--repair-binding', 'Clear a stale local Cloud binding if the remote course was deleted, then continue')
-  .option('--password', 'Password-protect preview (interactive prompt, requires --preview)')
+  .option('--password [password]', 'Password-protect preview. Prompts if no value is provided.')
   .option('-m, --message <message>', 'Deploy reason (e.g. "Fixed accessibility issues")')
   .option('--local', 'Use local Cloud instance (http://localhost:3000)')
   .option('--json', 'Emit machine-readable JSON result')
@@ -404,6 +404,17 @@ program
     await status({ json: options.json, repairBinding: options.repairBinding });
   });
 
+program
+  .command('deployments')
+  .description('List recent Cloud deployments for current course')
+  .option('--local', 'Use local Cloud instance (http://localhost:3000)')
+  .option('--json', 'Output raw JSON')
+  .action(async (options) => {
+    const { deployments, setLocalMode } = await import('../lib/cloud.js');
+    if (options.local) setLocalMode();
+    await deployments({ json: options.json });
+  });
+
 program
   .command('preview-link')
   .description('Show or update the Cloud preview link for the current course')

package/framework/docs/FRAMEWORK_GUIDE.md

@@ -679,7 +679,12 @@ Runs **in Node.js** during build (via `vite.framework-dev.config.js` `closeBundl
 
 ### MCP `coursecode_lint` — Build-Time Only
 
-The MCP `coursecode_lint` tool runs the build linter (config validation, CSS class verification, structure checks). It does NOT include runtime errors. For runtime errors and contrast warnings, use `coursecode_errors` (lightweight — just errors and console logs) or `coursecode_state` (full state snapshot including errors).
+The MCP `coursecode_lint` tool runs the static/build-time linter (config validation, CSS class verification, structure checks). It does **not** inspect the running preview and does **not** include live runtime, browser console, or Vite build-watch diagnostics.
+
+Use:
+- `coursecode_lint` for static preflight validation after source/config edits
+- `coursecode_errors` for the live "what is broken right now?" preview rollup
+- `coursecode_state` when you also need current slide, TOC, engagement, LMS state, and diagnostics
 
 ### Shared Rules (`lib/validation-rules.js`)
 
@@ -861,16 +866,18 @@ The MCP server runs a **persistent headless Chrome** internally via `puppeteer-c
 
 ### Preview Server Ownership
 
-The MCP does **not** start or manage the preview server. The preview must be running before using runtime tools:
+The MCP does **not** start or manage the preview server. Runtime tools connect to an already-running preview server.
 
-- **Human**: run `coursecode preview` (or `npm run preview`) in a terminal
-- **AI agent**: use your terminal/command execution tool to run `npm run preview`
+- If preview is already running for the current project, use it. Do **not** start a second preview server.
+- If preview is not running, start it in a terminal with `coursecode preview`.
+- For framework development from this repo, use `npm run preview`.
+- AI agents may start preview only via their terminal/command execution tool, and only after confirming preview is not already running or after a runtime MCP tool reports that preview is not running.
 
 If the preview is not running, runtime tools fail fast with a clear error message.
 
 ### Setup
 
-1. Start the preview server externally (see above)
+1. Make sure the preview server is running externally (see above)
 2. Add to IDE MCP config:
 
 ```json
@@ -885,10 +892,12 @@ If the preview is not running, runtime tools fail fast with a clear error messag
 
 ### Runtime Tools (require preview server)
 
+Tool results include machine-readable `structuredContent` plus text content for compatibility. Tool failures use structured error payloads with stable `code`, `message`, `hint`, and optional `details` fields so AI clients can recover without parsing prose.
+
 | Tool | Purpose | Returns |
 |------|---------|--------|
-| `coursecode_state` | Full course snapshot | `{slide, toc, interactions, engagement, lmsState, apiLog, errors, frameworkLogs, consoleLogs}` |
-| `coursecode_errors` | Errors + console logs only | `{errors, consoleLogs, count, clean}` — same error sources as `coursecode_state`, without the state payload |
+| `coursecode_state` | Full course snapshot + live diagnostics | `{slide, toc, interactions, engagement, lmsState, apiLog, diagnostics, issues, errors, frameworkLogs, consoleLogs}` |
+| `coursecode_errors` | Live diagnostic rollup only | `{build, runtime, framework, console, issues, errors, count, clean}` — same diagnostic sources as `coursecode_state`, without the state payload |
 | `coursecode_navigate` | Go to slide by ID | `{slide, interactions, engagement, accessibility}` |
 | `coursecode_interact` | Set response + evaluate | `{interactionId, response}` → `{correct, score, feedback}` |
 | `coursecode_screenshot` | Visual capture (JPEG) | Optional `slideId` to navigate first, `fullPage` for scroll capture |
@@ -933,7 +942,7 @@ MCP Server (IDE) ──puppeteer──▶ Headless Chrome ──HTTP──▶ Pr
                                     └── Course iframe (CourseCodeAutomation API)
 ```
 
-- **Preview not running?** → Tools return clear error: "Start preview server first"
+- **Preview not running?** → Tools return a clear error. Start preview externally in a terminal, then retry.
 - **Chrome not found?** → Install Google Chrome or set `CHROME_PATH` env var
 
 ### Pre-Release Responsive Checks (Framework)

package/framework/docs/USER_GUIDE.md

@@ -297,7 +297,8 @@ Once connected, your AI assistant gains these capabilities:
 | `coursecode_screenshot` | Take a screenshot of any slide |
 | `coursecode_interact` | Answer an interaction and check if it's correct |
 | `coursecode_reset` | Clear progress and restart the course |
-| `coursecode_lint` | Check for errors (bad CSS classes, missing components, config issues) |
+| `coursecode_errors` | Check live preview diagnostics (build, runtime, framework, and console issues) |
+| `coursecode_lint` | Run static preflight checks (bad CSS classes, missing components, config issues) |
 | `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 |
@@ -306,7 +307,7 @@ Once connected, your AI assistant gains these capabilities:
 | `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 |
 
-> **Note:** The preview server must be running before using runtime tools like `coursecode_state`, `coursecode_screenshot`, or `coursecode_navigate`. Start it with `coursecode preview` in a terminal.
+> **Note:** The preview server must be running before using runtime tools like `coursecode_state`, `coursecode_errors`, `coursecode_screenshot`, or `coursecode_navigate`. If preview is not already running for this project, start it with `coursecode preview` in a terminal. Do not start a second preview server if one is already running.
 
 ### How the Workflow Changes
 
@@ -740,18 +741,42 @@ Open the URL in any browser, log in with your CourseCode account, and enter the
 - **Preview pointer** — the version served on the cloud preview link (for stakeholder review).
 - **deploy_mode** — a per-course or org setting in the Cloud dashboard. Default is auto-promote (new uploads immediately go live). Can be set to staged (new uploads require a manual promote step).
 - `--promote` and `--stage` are mutually exclusive.
+- `--password` can be combined with `--preview` to create or update the main preview link password. If you omit the password value in an interactive terminal, the CLI prompts for it. In `--json` mode you must pass the value explicitly.
 - **GitHub-linked courses:** If your course is connected to a GitHub repo in the Cloud dashboard, production deploys happen via `git push` — the CLI blocks direct production uploads. Use `coursecode deploy --preview` to push a preview build for stakeholder review.
 - If a cloud deployment was deleted outside the CLI and this project still has the old local binding, rerun with `coursecode deploy --repair-binding`. To clear the stale binding without deploying yet, run `coursecode status --repair-binding`.
 
+**Managing previews and pointers after deploy:**
+
+Use these commands when you want to change Cloud state without rebuilding the course:
+
+```bash
+coursecode status
+coursecode deployments
+coursecode promote --preview
+coursecode promote --production
+coursecode preview-link --enable
+coursecode preview-link --password
+coursecode preview-link --remove-password
+coursecode preview-link --expires-in-days 7
+coursecode preview-link --disable
+```
+
+- `coursecode deployments` lists recent immutable deployments and marks the current Production and Preview pointers.
+- `coursecode promote --preview` moves the Preview pointer to an existing deployment. If you do not pass `--deployment <id>`, the CLI prompts you to pick from recent deployments.
+- `coursecode promote --production` moves the Production pointer. Preview-only deployments cannot be promoted to Production.
+- `coursecode preview-link` manages the main preview link. That link follows the Preview pointer, so the URL can stay the same while you choose which deployment reviewers see.
+- Cloud can also create additional pinned preview links for specific deployments in the web app. The main CLI preview link is the pointer-following link.
+
 **Typical Cloud workflow:**
 1. Run `coursecode login` once, open the URL shown, and enter the code.
-2. Run `coursecode deploy` from your project folder.
+2. Run `coursecode deploy` from your project folder, or `coursecode deploy --preview --password` for a password-protected review build.
 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.
+4. Use the main preview link for review.
+5. Move the Preview or Production pointer when needed.
+6. 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.
+- Use **CourseCode Desktop** for the same project workflow with buttons for Preview / Export / Deploy, plus a focused Cloud Deployments panel for preview-link password/expiry management, recent deployments, and Production/Preview pointer changes.
 - Desktop docs: `coursecode-desktop/USER_GUIDE.md`
 
 **When to use Cloud vs local export:**
@@ -761,7 +786,7 @@ Open the URL in any browser, log in with your CourseCode account, and enter the
 **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
-- **Preview sharing** — cloud provides a shareable preview link automatically
+- **Preview sharing** — cloud provides a shareable preview link that can be password-protected and pointed at the review deployment you choose
 
 ### Exporting Content for Review
 

package/framework/js/automation/api-interactions.js

@@ -6,7 +6,7 @@
 
 import interactionRegistry from '../managers/interaction-registry.js';
 import { courseConfig } from '../../../course/course-config.js';
-import { recordInteractionResult } from '../components/interactions/interaction-base.js';
+import { getInteractionState, recordInteractionResult } from '../components/interactions/interaction-base.js';
 import { logger } from '../utilities/logger.js';
 
 /**
@@ -18,11 +18,26 @@ export function createInteractionMethods(logTrace) {
     return {
         listInteractions() {
             const interactions = interactionRegistry.getAll();
-            const simplifiedList = interactions.map(i => ({
-                id: i.id,
-                type: i.type,
-                description: i.description
-            }));
+            const simplifiedList = interactions.map(i => {
+                const savedState = getInteractionState(i.id);
+                let response = savedState?.response;
+
+                if (response === undefined && typeof i.instance?.getResponse === 'function') {
+                    try {
+                        response = i.instance.getResponse();
+                    } catch {
+                        response = undefined;
+                    }
+                }
+
+                return {
+                    id: i.id,
+                    type: i.type,
+                    description: i.description,
+                    hasResponse: response !== null && response !== undefined && response !== '',
+                    isChecked: savedState?.submitted === true
+                };
+            });
             logTrace('listInteractions', { count: simplifiedList.length });
             return simplifiedList;
         },
@@ -33,10 +48,23 @@ export function createInteractionMethods(logTrace) {
                 throw new Error(`CourseCodeAutomation: Interaction "${interactionId}" not found on the current slide`);
             }
             logTrace('getInteractionMetadata', { interactionId });
+            const savedState = getInteractionState(entry.id);
+            let response = savedState?.response;
+
+            if (response === undefined && typeof entry.instance?.getResponse === 'function') {
+                try {
+                    response = entry.instance.getResponse();
+                } catch {
+                    response = undefined;
+                }
+            }
+
             return {
                 id: entry.id,
                 type: entry.type,
-                description: entry.description
+                description: entry.description,
+                hasResponse: response !== null && response !== undefined && response !== '',
+                isChecked: savedState?.submitted === true
             };
         },
 

package/lib/cloud.js

@@ -1036,6 +1036,28 @@ export async function deploy(options = {}) {
   const promoteMode = options.promote ? 'promote' : options.stage ? 'stage' : 'auto';
   const previewForce = !!options.preview;
   const previewOnly = previewForce && promoteMode === 'auto';
+  let previewPassword;
+  if (options.password !== undefined) {
+    if (!previewForce) {
+      logErr('\n❌ --password requires --preview.\n');
+      if (options.json) process.stdout.write(JSON.stringify({ success: false, error: '--password requires --preview' }) + '\n');
+      process.exit(1);
+    }
+    previewPassword = options.password;
+    if (previewPassword === true || previewPassword === '') {
+      if (options.json) {
+        logErr('\n❌ --password requires a value when using --json.\n');
+        process.stdout.write(JSON.stringify({ success: false, error: '--password requires a value when using --json' }) + '\n');
+        process.exit(1);
+      }
+      previewPassword = await prompt('  Preview password: ');
+    }
+    if (!previewPassword) {
+      logErr('\n❌ Preview password cannot be empty.\n');
+      if (options.json) process.stdout.write(JSON.stringify({ success: false, error: 'Preview password cannot be empty' }) + '\n');
+      process.exit(1);
+    }
+  }
 
   log('\n📦 Building...\n');
   emitProgress('building');
@@ -1196,6 +1218,7 @@ export async function deploy(options = {}) {
     previewForce,
     previewOnly,
   };
+  if (previewPassword) finalizeBody.previewPassword = previewPassword;
   if (options.message) finalizeBody.message = options.message;
 
   const finalizeRes = await cloudFetch(
@@ -1544,6 +1567,51 @@ export async function status(options = {}) {
   console.log('');
 }
 
+/**
+ * coursecode deployments — list recent deployments for the current course
+ */
+export async function deployments(options = {}) {
+  await ensureAuthenticated();
+  const slug = resolveSlug();
+  const rcConfig = readRcConfig();
+  const orgQuery = rcConfig?.orgId ? `?orgId=${rcConfig.orgId}` : '';
+
+  const makeRequest = async (_isRetry = false) => {
+    const token = readCredentials()?.token;
+    const res = await cloudFetch(
+      `/api/cli/courses/${encodeURIComponent(slug)}/versions${orgQuery}`,
+      {},
+      token
+    );
+    return handleResponse(res, { retryFn: makeRequest, _isRetry });
+  };
+
+  const data = await makeRequest();
+
+  if (options.json) {
+    process.stdout.write(JSON.stringify(data) + '\n');
+    return;
+  }
+
+  const rows = data.deployments ?? [];
+  if (rows.length === 0) {
+    console.log('\nNo deployments found for this course.\n');
+    return;
+  }
+
+  console.log(`\n${slug} — Recent Deployments\n`);
+  rows.forEach((deployment, index) => {
+    const marker = deployment.id === data.production_deployment_id
+      ? ' [production]'
+      : deployment.id === data.preview_deployment_id
+        ? ' [preview]'
+        : '';
+    const flags = deployment.preview_only ? 'preview-only' : deployment.source;
+    console.log(`  ${index + 1}. ${formatDate(deployment.created_at)} — ${deployment.file_count} files, ${formatBytes(deployment.total_size)} — ${flags}${marker}`);
+  });
+  console.log('');
+}
+
 /**
  * coursecode preview-link — show or update the current preview link
  */
@@ -1794,4 +1862,3 @@ export async function deleteCourse(options = {}) {
   }
   console.log('');
 }
-

package/lib/headless-browser.js

@@ -358,8 +358,8 @@ class HeadlessBrowser {
 
         // Navigate to specific slide if requested
         if (slideId) {
-            await this.evaluate((id) => {
-                window.CourseCodeAutomation.goToSlide(id);
+            await this.evaluate(async (id) => {
+                await window.CourseCodeAutomation.goToSlide(id);
             }, slideId);
             // Wait for slide transition
             await new Promise(resolve => setTimeout(resolve, 500));

package/lib/mcp-prompts.js

@@ -20,7 +20,7 @@ export const TOOLS = [
     // --- Runtime Tools (require headless browser) ---
     {
         name: 'coursecode_state',
-        description: `Get course state, runtime errors, and warnings in one call. This is the primary tool for checking errors.
+        description: `Get course state and live preview diagnostics in one call.
 
 Returns:
 - slide: current slide ID (string)
@@ -29,12 +29,15 @@ Returns:
 - engagement: slide engagement {complete, percentage, requirements}
 - lmsState: LMS data {score, completion, success, bookmark, format, objectives, state}
 - apiLog: last 20 LMS API calls [{timestamp, method, args, result}]
-- errors: runtime errors/warnings [{type, message, hint, isWarning}]
+- diagnostics: live issue rollup with build, runtime, framework, console, issues, count, clean
+- issues/errors: flat live issue list [{source, severity, isWarning, type, message, hint?}]
+- runtimeErrors: runtime/debug-panel errors and warnings only
+- buildErrors/buildWarnings: backward-compatible build-watch aliases
 - frameworkLogs: structured framework log events [{level, domain, operation, message, stack?, timestamp}]
 - consoleLogs: browser console warnings/errors [{type, text, time}]
 
 Use this first to understand the course state before taking actions.
-For error checking only (after file edits), prefer coursecode_errors — same error sources, smaller payload.
+For checking what is broken after file edits, prefer coursecode_errors — same live diagnostic sources, smaller payload.
 Requires preview server to be running.`,
         inputSchema: {
             type: 'object',
@@ -48,15 +51,23 @@ Requires preview server to be running.`,
     },
     {
         name: 'coursecode_errors',
-        description: `Get runtime errors and warnings from the live preview. Uses the same error sources as coursecode_state (preview server errors + browser console) but without the heavyweight state payload.
+        description: `Get all current live preview diagnostics without the heavyweight course state payload.
+
+This is the primary "what is broken right now?" tool after edits. It aggregates:
+- build: Vite/build-watch errors and warnings from the running preview server
+- runtime: stub LMS/debug-panel errors and warnings
+- framework: CourseCode logger warnings/errors
+- console: browser console warnings/errors
+
+This is different from coursecode_lint, which is a static/build-time linter and does not inspect the running preview.
 
 Returns:
-- errors: [{type, message, hint?, isWarning?}] — preview server errors and warnings
-- consoleLogs: [{type, text, time}] — browser console warnings/errors
-- count: total number of errors + console logs
-- clean: true if no errors, warnings, or console issues
+- build/runtime/framework/console: grouped diagnostics by source
+- issues/errors: flat list [{source, severity, isWarning, type, message, hint?}] for agents
+- count: total issue count
+- clean: true if no live issues were found
+- runtimeErrors/frameworkLogs/consoleLogs: source-specific aliases
 
-Use after making file changes to check for breakage without the overhead of coursecode_state.
 Requires preview server to be running.`,
         inputSchema: {
             type: 'object',
@@ -378,16 +389,16 @@ Use to discover available interactions before creating assessments.`,
     },
     {
         name: 'coursecode_lint',
-        description: `Run the course linter and get structured results.
+        description: `Run the static course linter and get structured results.
 
-Always runs build-time lint (config, CSS classes, structure). Does NOT include runtime errors — use coursecode_state for runtime errors and contrast warnings when the preview server is running.
+This is a preflight/static validation tool for config, source structure, CSS class names, and schema rules. It does NOT inspect the running preview and does NOT include live runtime, browser console, or Vite build-watch diagnostics. Use coursecode_errors for the live "what is broken right now?" view when preview is running.
 
 Returns:
 - errors: [{slideId?, rule, message, severity, hint?}]
 - warnings: [{slideId?, rule, message, severity, hint?}]
 - passed: boolean
 
-Build-time rules (always checked):
+Static rules (always checked):
 - undefined-css-class: hallucinated or stale class names (with fix suggestions)
 - unknown-component: unregistered data-component types
 - requirement-missing-component: engagement requirement without matching component
@@ -396,7 +407,7 @@ Build-time rules (always checked):
 - assessment-id-mismatch: config ID doesn't match assessment ID
 - invalid-gating: bad gating condition configuration
 
-Use AFTER making changes to validate the course.`,
+Use after making source/config changes as a fast static check. Then use coursecode_errors against the running preview for live diagnostics.`,
         inputSchema: {
             type: 'object',
             properties: {},
@@ -764,12 +775,16 @@ All runtime tools (state, navigate, interact, screenshot, viewport, reset) execu
 
 ### Preview Server Ownership
 - The MCP does NOT start or manage the preview server
-- The preview must be started externally: run \`coursecode preview\` in a terminal (human) or via a terminal/command execution tool (AI agent)
-- If preview is not running, runtime tools will fail with a clear error message
+- Before using runtime tools, check whether preview is already running for this project
+- If preview is already running, use it; do not start a second preview server
+- If preview is not running, start it externally in a terminal: run \`coursecode preview\` (or \`npm run preview\` for framework development)
+- AI agents may start preview only via a terminal/command execution tool, and only after a runtime tool reports that preview is not running
 - The headless browser auto-reconnects when Vite rebuilds (file changes)
 
 ### Navigation API
-- coursecode_state → get slim TOC with slide IDs, current slide, interactions, engagement, lmsState, apiLog, errors, frameworkLogs, consoleLogs
+- coursecode_state → get slim TOC with slide IDs, current slide, interactions, engagement, lmsState, apiLog, diagnostics, frameworkLogs, consoleLogs
+- coursecode_errors → get live diagnostics only (build/runtime/framework/console); use this after edits
+- coursecode_lint → run static preflight lint only; it is not a live preview diagnostic
 - coursecode_navigate(slideId) → go to any slide instantly by ID
 - 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)

package/lib/mcp-server.js

@@ -37,6 +37,178 @@ import { TOOLS, buildInstructions, getWorkflowStatusWithInstructions } from './m
 
 const DEFAULT_PORT = 4173;
 
+class McpToolError extends Error {
+    constructor(code, message, options = {}) {
+        super(message);
+        this.name = 'McpToolError';
+        this.code = code;
+        this.hint = options.hint;
+        this.details = options.details;
+    }
+}
+
+function normalizePort(port) {
+    const parsed = parseInt(port ?? DEFAULT_PORT, 10);
+    return Number.isFinite(parsed) ? parsed : DEFAULT_PORT;
+}
+
+function makeToolResult(result) {
+    return {
+        content: [{
+            type: 'text',
+            text: JSON.stringify(result, null, 2)
+        }],
+        structuredContent: result
+    };
+}
+
+function normalizeToolError(error) {
+    if (error instanceof McpToolError) {
+        return {
+            code: error.code,
+            message: error.message,
+            ...(error.hint ? { hint: error.hint } : {}),
+            ...(error.details ? { details: error.details } : {})
+        };
+    }
+
+    const message = error?.message || String(error);
+    if (/Preview server not running/i.test(message)) {
+        return {
+            code: 'preview_not_running',
+            message,
+            hint: 'Start the CourseCode preview server for this project, then retry the MCP tool call.'
+        };
+    }
+
+    if (/Slide ".*" not found/i.test(message)) {
+        return {
+            code: 'invalid_slide_id',
+            message,
+            hint: 'Call coursecode_state to get valid slide IDs, then retry with one of those IDs.'
+        };
+    }
+
+    if (/is required|Provide either/i.test(message)) {
+        return {
+            code: 'invalid_arguments',
+            message,
+            hint: 'Check the tool input schema and retry with the required arguments.'
+        };
+    }
+
+    if (/Unknown tool:/i.test(message)) {
+        return {
+            code: 'unknown_tool',
+            message,
+            hint: 'Call tools/list and retry with one of the advertised CourseCode tool names.'
+        };
+    }
+
+    return {
+        code: 'tool_failed',
+        message,
+        hint: 'Inspect the message and retry after correcting the underlying issue.'
+    };
+}
+
+function makeToolErrorResult(error) {
+    const normalized = normalizeToolError(error);
+    const result = {
+        success: false,
+        error: normalized,
+        code: normalized.code,
+        message: normalized.message,
+        ...(normalized.hint ? { hint: normalized.hint } : {}),
+        ...(normalized.details ? { details: normalized.details } : {})
+    };
+
+    return {
+        content: [{
+            type: 'text',
+            text: JSON.stringify(result, null, 2)
+        }],
+        structuredContent: result,
+        isError: true
+    };
+}
+
+function normalizeIssue(source, severity, issue) {
+    const isWarning = severity === 'warning' || issue?.isWarning === true || issue?.level === 'warn';
+    return {
+        source,
+        severity: isWarning ? 'warning' : 'error',
+        isWarning,
+        type: issue?.type || issue?.domain || source,
+        message: issue?.message || issue?.text || String(issue),
+        ...(issue?.hint ? { hint: issue.hint } : {}),
+        ...(issue?.operation ? { operation: issue.operation } : {}),
+        ...(issue?.time ? { time: issue.time } : {}),
+        ...(issue?.timestamp ? { timestamp: issue.timestamp } : {})
+    };
+}
+
+async function getLiveDiagnostics(port, frameworkLogs = []) {
+    const diagnostics = {
+        build: { errors: [], warnings: [] },
+        runtime: { errors: [], warnings: [] },
+        framework: { errors: [], warnings: [] },
+        console: { errors: [], warnings: [] },
+        issues: []
+    };
+
+    try {
+        const buildResp = await fetch(`http://localhost:${port}/__mcp/errors`);
+        if (buildResp.ok) {
+            const buildData = await buildResp.json();
+            diagnostics.build.errors = buildData.errors || [];
+            diagnostics.build.warnings = buildData.warnings || [];
+        }
+    } catch {
+        // Preview build diagnostics unavailable — leave empty.
+    }
+
+    try {
+        const errResp = await fetch(`http://localhost:${port}/__lms/errors`);
+        if (errResp.ok) {
+            const errData = await errResp.json();
+            diagnostics.runtime.errors = errData.errors || [];
+            diagnostics.runtime.warnings = errData.warnings || [];
+        }
+    } catch {
+        // Runtime diagnostics unavailable — leave empty.
+    }
+
+    for (const log of frameworkLogs || []) {
+        if (log.level === 'warn') diagnostics.framework.warnings.push(log);
+        else if (log.level === 'error' || log.level === 'fatal') diagnostics.framework.errors.push(log);
+    }
+
+    const consoleLogs = headless.getConsoleLogs();
+    for (const log of consoleLogs) {
+        // logger.warn/error entries are already represented as structured
+        // framework diagnostics, so do not double-count their console echo.
+        if (/^\[(WARN|ERROR|FATAL)\]/.test(log.text || '')) continue;
+        if (log.type === 'warning') diagnostics.console.warnings.push(log);
+        else diagnostics.console.errors.push(log);
+    }
+
+    diagnostics.issues = [
+        ...diagnostics.build.errors.map(issue => normalizeIssue('build', 'error', issue)),
+        ...diagnostics.build.warnings.map(issue => normalizeIssue('build', 'warning', issue)),
+        ...diagnostics.runtime.errors.map(issue => normalizeIssue('runtime', 'error', issue)),
+        ...diagnostics.runtime.warnings.map(issue => normalizeIssue('runtime', 'warning', issue)),
+        ...diagnostics.framework.errors.map(issue => normalizeIssue('framework', 'error', issue)),
+        ...diagnostics.framework.warnings.map(issue => normalizeIssue('framework', 'warning', issue)),
+        ...diagnostics.console.errors.map(issue => normalizeIssue('console', 'error', issue)),
+        ...diagnostics.console.warnings.map(issue => normalizeIssue('console', 'warning', issue))
+    ];
+
+    diagnostics.count = diagnostics.issues.length;
+    diagnostics.clean = diagnostics.count === 0;
+    return diagnostics;
+}
+
 /**
  * Ensure headless browser is connected to preview server.
  * Fails fast if preview is not running — humans own the preview lifecycle.
@@ -60,7 +232,7 @@ async function ensureHeadless(port) {
  * Create and run the MCP server
  */
 export async function startMcpServer(options = {}) {
-    const port = options.port || DEFAULT_PORT;
+    const port = normalizePort(options.port);
     
     // Build dynamic instructions for current authoring stage
     const instructions = await buildInstructions(port);
@@ -68,10 +240,10 @@ export async function startMcpServer(options = {}) {
     const server = new Server(
         {
             name: 'coursecode',
-            version: '2.0.0',
-            instructions
+            version: '2.0.0'
         },
         {
+            instructions,
             capabilities: {
                 tools: {}
             }
@@ -106,29 +278,32 @@ export async function startMcpServer(options = {}) {
                             lmsState: api.getLmsState()
                         };
                     });
-                    // Read API log and error log from preview server (same data user sees in debug panel)
+                    // Read API log plus a unified diagnostic rollup from the preview server/headless page.
                     try {
-                        const [logResp, errResp] = await Promise.all([
-                            fetch(`http://localhost:${port}/__lms/log`),
-                            fetch(`http://localhost:${port}/__lms/errors`)
-                        ]);
+                        const logResp = await fetch(`http://localhost:${port}/__lms/log`);
                         result.apiLog = logResp.ok ? (await logResp.json()).entries?.slice(0, 20) || [] : [];
-                        if (errResp.ok) {
-                            const errData = await errResp.json();
-                            result.errors = [...(errData.errors || []), ...(errData.warnings || [])];
-                        } else {
-                            result.errors = [];
-                        }
                     } catch {
                         result.apiLog = [];
-                        result.errors = [];
                     }
-                    // Append console errors/warnings captured from the page
-                    result.consoleLogs = headless.getConsoleLogs();
+                    result.diagnostics = await getLiveDiagnostics(port, result.frameworkLogs);
+                    result.issues = result.diagnostics.issues;
+                    result.errors = result.diagnostics.issues;
+                    result.runtimeErrors = [
+                        ...result.diagnostics.runtime.errors,
+                        ...result.diagnostics.runtime.warnings
+                    ];
+                    result.buildErrors = result.diagnostics.build.errors;
+                    result.buildWarnings = result.diagnostics.build.warnings;
+                    result.consoleLogs = [
+                        ...result.diagnostics.console.errors,
+                        ...result.diagnostics.console.warnings
+                    ];
                     break;
 
                 case 'coursecode_navigate':
-                    if (!args?.slideId) throw new Error('slideId is required');
+                    if (!args?.slideId) throw new McpToolError('missing_required_argument', 'slideId is required', {
+                        hint: 'Call coursecode_state to get valid slide IDs, then pass one as slideId.'
+                    });
                     await ensureHeadless(port);
                     // Apply accessibility preferences before navigation
                     if (args.theme || args.highContrast !== undefined) {
@@ -147,11 +322,14 @@ export async function startMcpServer(options = {}) {
                             return toc.some(item => item.id === slideId);
                         }, args.slideId);
                         if (!validSlide) {
-                            throw new Error(`Slide "${args.slideId}" not found. Use coursecode_state to get valid slide IDs.`);
+                            throw new McpToolError('invalid_slide_id', `Slide "${args.slideId}" not found.`, {
+                                hint: 'Call coursecode_state to get valid slide IDs, then retry with one of those IDs.',
+                                details: { slideId: args.slideId }
+                            });
                         }
                     }
-                    await headless.evaluate((slideId) => {
-                        window.CourseCodeAutomation.goToSlide(slideId);
+                    await headless.evaluate(async (slideId) => {
+                        await window.CourseCodeAutomation.goToSlide(slideId);
                     }, args.slideId);
                     // State updates asynchronously after navigation
                     await new Promise(resolve => setTimeout(resolve, 50));
@@ -167,8 +345,12 @@ export async function startMcpServer(options = {}) {
                     break;
 
                 case 'coursecode_interact':
-                    if (!args?.interactionId) throw new Error('interactionId is required');
-                    if (args.response === undefined) throw new Error('response is required');
+                    if (!args?.interactionId) throw new McpToolError('missing_required_argument', 'interactionId is required', {
+                        hint: 'Call coursecode_state on the target slide to list valid interaction IDs.'
+                    });
+                    if (args.response === undefined) throw new McpToolError('missing_required_argument', 'response is required', {
+                        hint: 'Pass a response value matching the interaction type.'
+                    });
                     await ensureHeadless(port);
                     result = await headless.evaluate(({ interactionId, response }) => {
                         const api = window.CourseCodeAutomation;
@@ -204,7 +386,10 @@ export async function startMcpServer(options = {}) {
                             return toc.some(item => item.id === slideId);
                         }, args.slideId);
                         if (!validSlide) {
-                            throw new Error(`Slide "${args.slideId}" not found. Use coursecode_state to get valid slide IDs.`);
+                            throw new McpToolError('invalid_slide_id', `Slide "${args.slideId}" not found.`, {
+                                hint: 'Call coursecode_state to get valid slide IDs, then retry with one of those IDs.',
+                                details: { slideId: args.slideId }
+                            });
                         }
                     }
                     result = await headless.screenshot({
@@ -228,30 +413,33 @@ export async function startMcpServer(options = {}) {
                     } 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.');
+                        throw new McpToolError('missing_required_argument', 'Provide either a breakpoint name or both width and height.', {
+                            hint: 'Use breakpoint: "desktop" or pass explicit width and height numbers.'
+                        });
                     }
                     break;
 
                 case 'coursecode_errors': {
-                    // Same error-gathering mechanism as coursecode_state,
-                    // but without the heavyweight state payload (TOC, interactions, etc.)
+                    // Live diagnostic rollup without the heavyweight state payload (TOC, interactions, etc.).
                     await ensureHeadless(port);
-                    let errors = [];
-                    try {
-                        const errResp = await fetch(`http://localhost:${port}/__lms/errors`);
-                        if (errResp.ok) {
-                            const errData = await errResp.json();
-                            errors = [...(errData.errors || []), ...(errData.warnings || [])];
-                        }
-                    } catch {
-                        // Preview server unreachable — errors array stays empty
-                    }
-                    const consoleLogs = headless.getConsoleLogs();
+                    const frameworkLogs = await headless.evaluate(() => {
+                        return window.CourseCodeAutomation.getFrameworkLogs();
+                    });
+                    const diagnostics = await getLiveDiagnostics(port, frameworkLogs);
                     result = {
-                        errors,
-                        consoleLogs,
-                        count: errors.length + consoleLogs.length,
-                        clean: errors.length === 0 && consoleLogs.length === 0
+                        ...diagnostics,
+                        // Convenience aliases for agents that expect a flat list.
+                        issues: diagnostics.issues,
+                        errors: diagnostics.issues,
+                        runtimeErrors: [
+                            ...diagnostics.runtime.errors,
+                            ...diagnostics.runtime.warnings
+                        ],
+                        frameworkLogs,
+                        consoleLogs: [
+                            ...diagnostics.console.errors,
+                            ...diagnostics.console.warnings
+                        ]
                     };
                     break;
                 }
@@ -295,23 +483,15 @@ export async function startMcpServer(options = {}) {
 
 
                 default:
-                    throw new Error(`Unknown tool: ${name}`);
+                    throw new McpToolError('unknown_tool', `Unknown tool: ${name}`, {
+                        hint: 'Call tools/list and retry with one of the advertised CourseCode tool names.',
+                        details: { name }
+                    });
             }
-            
-            return {
-                content: [{
-                    type: 'text',
-                    text: JSON.stringify(result, null, 2)
-                }]
-            };
+
+            return makeToolResult(result);
         } catch (error) {
-            return {
-                content: [{
-                    type: 'text',
-                    text: `Error: ${error.message}`
-                }],
-                isError: true
-            };
+            return makeToolErrorResult(error);
         }
     });
 
@@ -355,6 +535,7 @@ export async function startMcpServer(options = {}) {
 if (process.argv[1]?.endsWith('mcp-server.js')) {
     const args = process.argv.slice(2);
     const portArg = args.find(a => a.startsWith('--port='));
-    const port = portArg ? parseInt(portArg.split('=')[1], 10) : DEFAULT_PORT;
+    const portValue = portArg ? portArg.split('=')[1] : args[args.indexOf('--port') + 1];
+    const port = normalizePort(portValue);
     startMcpServer({ port });
 }

package/lib/preview-server.js

@@ -269,6 +269,11 @@ export async function previewServer(options = {}) {
     viteProcess.stdout.on('data', (data) => {
         const output = data.toString();
         process.stdout.write(output);
+        if (output.includes('Building...')) {
+            buildState.errors = [];
+            buildState.warnings = [];
+            buildState.lastBuildSuccess = false;
+        }
         if (output.includes('Build complete')) {
             buildState.lastBuildTime = new Date().toISOString();
             buildState.lastBuildSuccess = true;

package/package.json

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