coursecode 0.1.23 → 0.1.25

package/README.md

@@ -1,22 +1,14 @@
 # CourseCode
 
-**Open-source, local-first course authoring with AI help — no coding required to start, full code control when you need it.**
+**Open-source, local-first course authoring built for AI tools like Claude Code, Codex, Cursor, and [CourseCode Desktop](https://coursecodedesktop.com) — no coding required to start, full code control when you need it.**
 
-CourseCode creates real project files you can inspect, version, and edit directly — with a predictable, file-based workflow instead of a black-box GUI.
+CourseCode creates real project files you can inspect, version, and edit directly — with a predictable, file-based workflow instead of a black-box GUI. Built-in MCP integration means your AI assistant connects directly to your course project.
 
 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
-
-Start with the workflow that fits you:
-
-- **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
+- **MCP integration**: Works with Claude Code, Codex, Cursor, CourseCode Desktop, and any MCP-capable AI tool — previews, screenshots, linting, and testing without manual file sharing
 - **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
@@ -35,9 +27,7 @@ Start with the workflow that fits you:
 
 ## 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.
+> **Prefer a GUI?** Use [CourseCode Desktop](https://coursecodedesktop.com) instead.
 
 ### Required
 
@@ -71,7 +61,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?** 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).
+Start with the [User Guide](framework/docs/USER_GUIDE.md) for a complete walkthrough.
 
 ---
 

package/framework/docs/FRAMEWORK_GUIDE.md

@@ -662,6 +662,10 @@ Runs **in Node.js** during build (via `vite.framework-dev.config.js` `closeBundl
 
 **Errors fail the build; warnings print but don't block.**
 
+### MCP `coursecode_lint` — Unified Results
+
+The MCP `coursecode_lint` tool always runs the build linter. When the preview server is running and the headless browser is connected, it also merges runtime lint results (contrast, touch targets, spacing, layout) into the same response. Runtime-sourced items are tagged with `source: 'runtime'` and `rule: 'runtime-lint'`. The `runtimeLintIncluded` flag in the response indicates whether runtime checks were included. This gives AI agents a single, low-token-cost tool for all lint results without needing to pull the full course state via `coursecode_state`.
+
 ### Shared Rules (`lib/validation-rules.js`)
 
 Pure validation functions used by **both** linters. No environment-specific code (no DOM, no `fs`). Includes assessment validation, engagement validation, and result formatting.

package/lib/mcp-prompts.js

@@ -306,14 +306,17 @@ Use to discover available interactions before creating assessments.`,
 
     {
         name: 'coursecode_lint',
-        description: `Run the build-time linter and get structured results.
+        description: `Run the course linter and get structured results.
+
+Always runs build-time lint (config, CSS classes, structure). When the preview server is running and the headless browser is connected, also includes runtime lint results (contrast, touch targets, spacing, layout).
 
 Returns:
-- errors: [{slideId, rule, message, severity}]
-- warnings: [{slideId, rule, message, severity, class?, suggestion?}]
+- errors: [{slideId?, rule, message, severity, source?, hint?}]
+- warnings: [{slideId?, rule, message, severity, source?, class?, suggestion?, hint?}]
 - passed: boolean
+- runtimeLintIncluded: boolean (true when runtime checks were included)
 
-Rules detected:
+Build-time 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
@@ -322,9 +325,11 @@ Rules detected:
 - assessment-id-mismatch: config ID doesn't match assessment ID
 - invalid-gating: bad gating condition configuration
 
-The runtime linter (visible via coursecode_state errors/warnings) also checks:
-- Spacing: flex/grid containers without gap, adjacent elements with no margin, containers with no padding
-- Contrast, touch targets, text proximity to borders, element overlap, styled lists
+Runtime rules (included when preview is running, source='runtime'):
+- Contrast ratio violations
+- Touch target size violations
+- Spacing issues (missing gap, margin, padding)
+- Text proximity to borders, element overlap, styled lists
 
 Suppression: Add data-lint-ignore to any HTML element to suppress warnings for it and children.
   data-lint-ignore           — suppress all warnings

package/lib/mcp-server.js

@@ -247,6 +247,46 @@ export async function startMcpServer(options = {}) {
                     break;
                 case 'coursecode_lint':
                     result = await lintCourse();
+                    // Merge runtime lint errors if headless browser is already connected
+                    if (headless.isRunning()) {
+                        try {
+                            const runtimeErrors = await headless.evaluateParent(() => {
+                                return window._stubPlayerState?.errorLog || [];
+                            });
+                            if (runtimeErrors.length > 0) {
+                                const runtimeWarnings = runtimeErrors.filter(e => e.isWarning);
+                                const runtimeErrs = runtimeErrors.filter(e => !e.isWarning);
+                                if (runtimeWarnings.length > 0) {
+                                    result.warnings = (result.warnings || []).concat(
+                                        runtimeWarnings.map(e => ({
+                                            severity: 'warning',
+                                            message: e.message,
+                                            hint: e.hint,
+                                            rule: 'runtime-lint',
+                                            source: 'runtime'
+                                        }))
+                                    );
+                                    result.warningCount = result.warnings.length;
+                                }
+                                if (runtimeErrs.length > 0) {
+                                    result.errors = (result.errors || []).concat(
+                                        runtimeErrs.map(e => ({
+                                            severity: 'error',
+                                            message: e.message,
+                                            hint: e.hint,
+                                            rule: 'runtime-lint',
+                                            source: 'runtime'
+                                        }))
+                                    );
+                                    result.errorCount = result.errors.length;
+                                    result.passed = result.errors.length === 0;
+                                }
+                                result.runtimeLintIncluded = true;
+                            }
+                        } catch {
+                            // Headless browser may have disconnected — non-fatal, build lint still valid
+                        }
+                    }
                     break;
 
                 case 'coursecode_export_content':

package/package.json

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