coursecode 0.1.27 → 0.1.29

package/lib/authoring-api.js

@@ -167,9 +167,8 @@ export function getAuthoringContext() {
 
 /**
  * Dynamic CSS catalog — extracts structured class data from real CSS files via PostCSS.
- * 
- * Without filterCategory: returns compact categorized index (class name → short description).
- * With filterCategory: returns full detail for that category (all declarations).
+ * Token values (spacing, font sizes, etc.) are resolved from design-tokens.css so
+ * AI sees actual values like "1rem" instead of opaque "var(--space-4)".
  * 
  * Category names are derived from file paths relative to framework/css/:
  *   utilities/borders.css → "utilities/borders"
@@ -177,8 +176,77 @@ export function getAuthoringContext() {
  *   components/hero.css → "components/hero"
  */
 
-// Module-level cache — parsed once per process
+// Module-level caches — parsed once per process
 let _cssCatalogCache = null;
+let _tokenMapCache = null;
+
+/**
+ * Parse design-tokens.css and resolve var() chains to final values.
+ * Returns a map of --variable-name → resolved-value.
+ */
+function buildTokenMap() {
+    if (_tokenMapCache) return _tokenMapCache;
+
+    const frameworkRoot = getFrameworkRoot();
+    const tokensFile = path.join(frameworkRoot, 'framework', 'css', 'design-tokens.css');
+
+    if (!fs.existsSync(tokensFile)) {
+        _tokenMapCache = {};
+        return _tokenMapCache;
+    }
+
+    const source = fs.readFileSync(tokensFile, 'utf-8');
+    const root = postcss.parse(source);
+    const tokens = {};
+
+    // Extract all custom properties from :root blocks
+    root.walk(node => {
+        if (node.type === 'decl' && node.prop.startsWith('--')) {
+            tokens[node.prop] = node.value.trim();
+        }
+    });
+
+    // Resolve var() chains iteratively (handles --space-4 → --space-4-base → 0.25rem)
+    for (let i = 0; i < 10; i++) {
+        let changed = false;
+        for (const [prop, value] of Object.entries(tokens)) {
+            const resolved = value.replace(/var\(\s*([^,)]+)\s*\)/g, (match, varName) => {
+                const trimmed = varName.trim();
+                if (tokens[trimmed] && !tokens[trimmed].includes('var(')) {
+                    changed = true;
+                    return tokens[trimmed];
+                }
+                return match;
+            });
+            tokens[prop] = resolved;
+        }
+        if (!changed) break;
+    }
+
+    _tokenMapCache = tokens;
+    return _tokenMapCache;
+}
+
+/**
+ * Replace var() references in a CSS value with resolved token values.
+ * Only resolves structural tokens (spacing, sizes, radii). Color tokens are
+ * left as var() references since semantic names like var(--bg-elevated) are
+ * more useful to AI than theme-dependent hex values like #1e293b.
+ */
+function resolveVarRefs(value, tokenMap) {
+    return value.replace(/var\(\s*([^,)]+?)(?:\s*,\s*([^)]+))?\s*\)/g, (_match, varName, fallback) => {
+        const resolved = tokenMap[varName.trim()];
+        if (resolved && !resolved.includes('var(')) {
+            // Skip color values — semantic variable names are more useful
+            if (/^#|^rgba?\(|^hsla?\(|^color-mix\(|^oklch\(/.test(resolved)) {
+                return _match;
+            }
+            return resolved;
+        }
+        if (fallback) return fallback.trim();
+        return _match;
+    });
+}
 
 function buildCssCatalog() {
     if (_cssCatalogCache) return _cssCatalogCache;
@@ -203,6 +271,9 @@ function buildCssCatalog() {
         // No course directory — framework-only mode
     }
 
+    // Resolve design tokens so declarations show real values
+    const tokenMap = buildTokenMap();
+
     const categories = {};
     let totalClasses = 0;
 
@@ -218,7 +289,7 @@ function buildCssCatalog() {
             const root = postcss.parse(source, { from: file });
             const classes = {};
 
-            extractClassCatalog(root, classes);
+            extractClassCatalog(root, classes, tokenMap);
 
             if (Object.keys(classes).length > 0) {
                 categories[category] = {
@@ -239,8 +310,9 @@ function buildCssCatalog() {
 /**
  * Extract class names with abbreviated declarations from PostCSS nodes.
  * Walks the AST and builds { className: "shortDescription" } entries.
+ * Token values are resolved so AI sees "1rem" instead of "var(--space-4)".
  */
-function extractClassCatalog(node, classes) {
+function extractClassCatalog(node, classes, tokenMap) {
     if (node.type === 'rule' && node.selector) {
         // Only process simple class selectors (e.g., .foo, .foo-bar)
         // Skip compound selectors, pseudo-classes, nested selectors
@@ -255,11 +327,12 @@ function extractClassCatalog(node, classes) {
             const className = simpleClassMatch[1];
             if (classes[className]) continue; // Already captured
 
-            // Build short description from declarations
+            // Build short description from declarations, resolving token values
             const decls = [];
             node.walk(child => {
                 if (child.type === 'decl') {
-                    decls.push(`${child.prop}: ${child.value}`);
+                    const resolved = resolveVarRefs(`${child.prop}: ${child.value}`, tokenMap);
+                    decls.push(resolved);
                 }
             });
 
@@ -276,34 +349,154 @@ function extractClassCatalog(node, classes) {
     // Recurse into @media, @supports, etc.
     if (node.nodes) {
         for (const child of node.nodes) {
-            extractClassCatalog(child, classes);
+            extractClassCatalog(child, classes, tokenMap);
         }
     }
 }
 
+// Internal categories — framework-managed CSS that authors don't write manually.
+// Filtered from TOC and search by default; always accessible via direct category drill-in.
+const INTERNAL_CATEGORY_PREFIXES = ['interactions/'];
+const INTERNAL_CATEGORIES = new Set([
+    'accessibility',
+    'components/assessments',
+    'components/audio-player',
+    'components/document-gallery',
+    'components/embed-frame',
+    'components/engagement',
+    'components/footer',
+    'components/notifications',
+    'components/sidebar',
+    'components/spinner',
+]);
+
+function isInternalCategory(category) {
+    if (INTERNAL_CATEGORY_PREFIXES.some(p => category.startsWith(p))) return true;
+    return INTERNAL_CATEGORIES.has(category);
+}
+
+// Brief descriptions for each author-facing category.
+// Shown in TOC mode so AI can navigate without drilling into every category.
+const CATEGORY_HINTS = {
+    'layout': 'Columns, splits, stacks, content widths (columns-*, split-*, content-*)',
+    'utilities/spacing': 'Margin (m-*), padding (p-*), gap (gap-*)',
+    'utilities/colors': 'Text (text-*) and background (bg-*) colors',
+    'utilities/typography': 'Font size, weight, line-height, alignment (text-sm, font-bold)',
+    'utilities/display': 'Display mode, overflow, position (d-flex, d-grid, d-none)',
+    'utilities/flexbox': 'Flex direction, alignment, wrapping, gap (flex-row, justify-center)',
+    'utilities/grid': 'CSS Grid columns, rows, spans',
+    'utilities/borders': 'Border width, radius, style (rounded-*, border-*)',
+    'utilities/animations': 'Transitions, entrance animations (fade-in, slide-up)',
+    'utilities/lists': 'List type, spacing, marker styles',
+    'utilities/visibility': 'Show/hide, opacity (visible, hidden, sr-only)',
+    'utilities/icons': 'Icon sizing, colors, alignment in text (icon-sm, icon-primary)',
+    'utilities/decorative': 'Dividers, gradients, shadows, overlays',
+    'utilities/tables': 'Table layout and cell utilities',
+    'utilities/container': 'Container width constraints',
+    'utilities/accessibility-utils': 'Screen reader, focus, skip-link helpers',
+    'components/cards': 'Card containers with headers, bodies, footers (card, card-*)',
+    'components/callouts': 'Info/warning/tip/danger callout boxes (callout, callout-*)',
+    'components/hero': 'Full-width hero banner sections',
+    'components/images': 'Image sizing, grids, rounded, shadow, captions (image-*)',
+    'components/tables': 'Table striping, borders, hover, compact variants',
+    'components/badges': 'Inline badge/label indicators (badge, badge-*)',
+    'components/buttons': 'Button variants and sizes (btn, btn-*)',
+    'components/tabs': 'Tab list and panel styling',
+    'components/accordions': 'Accordion panel structure and states',
+    'components/carousel': 'Carousel slide navigation',
+    'components/breadcrumbs': 'Breadcrumb path navigation',
+    'components/modals': 'Modal dialog overlays',
+    'components/tooltip': 'Hover tooltip styling',
+    'components/flip-cards': 'Front/back flip card containers',
+    'components/slide-header': 'Slide title and subtitle styling',
+    'components/forms': 'Form inputs, labels, validation',
+    'components/toggle': 'Toggle switch controls',
+    'components/checkbox-group': 'Grouped checkbox layouts',
+    'components/dropdown': 'Dropdown select menus',
+    'components/collapse': 'Collapsible content panels',
+    'components/lightbox': 'Fullscreen image viewer',
+    'components/video-player': 'Embedded video player',
+};
+
 /**
- * Get CSS catalog — compact list or full detail for one category.
- * @param {string} [filterCategory] - If provided, return detail for this category only
+ * Get CSS catalog — three access modes:
+ * 1. No args: compact TOC (category names + class counts)
+ * 2. category: full class list with declarations for one category
+ * 3. search: find classes by name across all categories
+ * 
+ * Internal categories (interactions, accessibility, app shell) are hidden by default.
+ * Set includeInternal: true to show them in TOC and search.
+ * Direct category access always works regardless of includeInternal.
+ * 
+ * @param {Object} [options]
+ * @param {string} [options.category] - Return full detail for this category
+ * @param {string} [options.search] - Search class names (substring match)
+ * @param {boolean} [options.includeInternal] - Include framework-internal categories (default: false)
  */
-export function getCssCatalog(filterCategory) {
+export function getCssCatalog({ category, search, includeInternal = false } = {}) {
     const catalog = buildCssCatalog();
 
-    if (filterCategory) {
-        const cat = catalog.categories[filterCategory];
+    // Mode: Category detail — always works, even for internal categories
+    if (category) {
+        const cat = catalog.categories[category];
         if (!cat) {
+            const available = Object.keys(catalog.categories)
+                .filter(c => includeInternal || !isInternalCategory(c))
+                .sort();
             return {
-                error: `Unknown category: '${filterCategory}'`,
-                available: Object.keys(catalog.categories).sort()
+                error: `Unknown category: '${category}'`,
+                available
             };
         }
-        return { category: filterCategory, ...cat };
+        return { category, ...cat };
+    }
+
+    // Mode: Search — case-insensitive substring match on class names
+    if (search) {
+        const query = search.toLowerCase();
+        const results = [];
+        for (const [cat, data] of Object.entries(catalog.categories)) {
+            if (!includeInternal && isInternalCategory(cat)) continue;
+            for (const [cls, declarations] of Object.entries(data.classes)) {
+                if (cls.toLowerCase().includes(query)) {
+                    results.push({ class: cls, category: cat, declarations });
+                }
+            }
+        }
+        const capped = results.length > 50;
+        return {
+            query: search,
+            results: results.slice(0, 50),
+            count: results.length,
+            capped,
+            message: capped
+                ? `Showing 50 of ${results.length} matches. Narrow your search or use 'category' to browse.`
+                : `${results.length} classes matching '${search}'.`
+        };
+    }
+
+    // Mode: TOC — category names, class counts, and hints
+    const categories = {};
+    let totalClasses = 0;
+    let filteredClasses = 0;
+    for (const [cat, data] of Object.entries(catalog.categories)) {
+        const count = Object.keys(data.classes).length;
+        if (!includeInternal && isInternalCategory(cat)) {
+            filteredClasses += count;
+            continue;
+        }
+        const entry = { count };
+        if (CATEGORY_HINTS[cat]) entry.hint = CATEGORY_HINTS[cat];
+        categories[cat] = entry;
+        totalClasses += count;
     }
 
     return {
-        categories: catalog.categories,
-        totalClasses: catalog.totalClasses,
-        categoryCount: Object.keys(catalog.categories).length,
-        message: `${catalog.totalClasses} CSS classes across ${Object.keys(catalog.categories).length} categories. Pass 'category' for full detail.`
+        categories,
+        totalClasses,
+        categoryCount: Object.keys(categories).length,
+        message: `${totalClasses} CSS classes across ${Object.keys(categories).length} categories. Use 'category' for full class list or 'search' to find classes by name.`
+            + (filteredClasses > 0 ? ` (${filteredClasses} internal classes hidden — use includeInternal: true to show)` : '')
     };
 }
 

package/lib/export-content.js

@@ -1139,6 +1139,10 @@ export async function getContentExport(options = {}) {
   const fullCoursePath = validateProject(coursePath, true);
   if (!fullCoursePath) return null;
 
+  // Size guard threshold — prevent unbounded context consumption.
+  // Only applies to full-course exports (no slides filter).
+  const MAX_UNFILTERED_SIZE = 40 * 1024; // 40KB
+
   try {
     const config = await loadCourseConfig(fullCoursePath);
 
@@ -1186,6 +1190,11 @@ export async function getContentExport(options = {}) {
     md += formatBranding(config);
     md += formatFeatures(config);
 
+    // Size guard: if full-course export exceeds threshold, return summary instead
+    if (!slides && md.length > MAX_UNFILTERED_SIZE) {
+      return buildExportSummary(config, structure, fullCoursePath, md.length, exportOptions);
+    }
+
     return md;
   } catch (error) {
     console.error('Failed to generate content export:', error.message);
@@ -1193,6 +1202,49 @@ export async function getContentExport(options = {}) {
   }
 }
 
+/**
+ * Build a compact summary when full export exceeds size threshold.
+ * Returns structure overview + per-slide sizes so AI can scope targeted exports.
+ */
+function buildExportSummary(config, structure, coursePath, totalSize, exportOptions) {
+  const meta = config.metadata || {};
+  let summary = `# ${meta.title || 'Untitled Course'} — Export Summary\n\n`;
+  summary += `> Full export is ${(totalSize / 1024).toFixed(0)}KB — too large for context. Use the \`slides\` parameter to export specific slides.\n\n`;
+
+  summary += '## Course Structure\n\n';
+  summary += generateStructureOverview(structure);
+  summary += '\n\n';
+
+  // Per-slide size estimates
+  summary += '## Slide Sizes\n\n';
+  summary += '| Slide ID | Title | Size |\n';
+  summary += '|----------|-------|------|\n';
+
+  function measureItems(items) {
+    for (const item of items) {
+      if (item.type === 'section') {
+        measureItems(item.children || []);
+      } else {
+        let content = '';
+        if (item.type === 'slide') {
+          content = formatSlide(item, coursePath, exportOptions);
+        } else if (item.type === 'assessment') {
+          content = formatAssessment(item, coursePath, exportOptions);
+        }
+        const sizeKB = (content.length / 1024).toFixed(1);
+        const title = item.title || item.menu?.label || item.id;
+        summary += `| \`${item.id}\` | ${title} | ${sizeKB}KB |\n`;
+      }
+    }
+  }
+
+  measureItems(structure);
+  summary += `\n**Total:** ${(totalSize / 1024).toFixed(0)}KB across all slides\n`;
+  summary += '\nUse `slides: "slide-id-1,slide-id-2"` to export specific slides, or `interactionsOnly: true` for just Q&A.\n';
+
+  return summary;
+}
+
 /**
  * Generate JSON output
  */

package/lib/mcp-prompts.js

@@ -39,6 +39,10 @@ Requires preview server to be running.`,
             type: 'object',
             properties: {},
             required: []
+        },
+        annotations: {
+            readOnlyHint: true,
+            idempotentHint: true
         }
     },
     {
@@ -71,6 +75,9 @@ Requires preview server to be running.`,
                 }
             },
             required: ['slideId']
+        },
+        annotations: {
+            idempotentHint: true
         }
     },
     {
@@ -102,6 +109,9 @@ Requires preview server to be running.`,
                 }
             },
             required: ['interactionId', 'response']
+        },
+        annotations: {
+            destructiveHint: false
         }
     },
     {
@@ -115,6 +125,10 @@ Requires preview server to be running.`,
             type: 'object',
             properties: {},
             required: []
+        },
+        annotations: {
+            destructiveHint: true,
+            idempotentHint: true
         }
     },
     {
@@ -153,6 +167,10 @@ Requires preview server to be running.`,
                 }
             },
             required: []
+        },
+        annotations: {
+            readOnlyHint: true,
+            idempotentHint: true
         }
     },
     {
@@ -188,9 +206,11 @@ Requires preview server to be running.`,
                 }
             },
             required: []
+        },
+        annotations: {
+            idempotentHint: true
         }
     },
-    // --- Workflow & Build Tools ---
     {
         name: 'coursecode_workflow_status',
         description: `Detect the current authoring stage and get stage-specific instructions.
@@ -215,6 +235,10 @@ Call this after completing a major milestone to get updated guidance for the nex
             type: 'object',
             properties: {},
             required: []
+        },
+        annotations: {
+            readOnlyHint: true,
+            idempotentHint: true
         }
     },
     {
@@ -240,27 +264,45 @@ Use in Stage 5 when the course is ready for export.`,
                 }
             },
             required: []
+        },
+        annotations: {
+            idempotentHint: true
         }
     },
-    // --- Catalog & Validation Tools (filesystem, no preview needed) ---
     {
         name: 'coursecode_css_catalog',
-        description: `Get CSS class information extracted from real CSS source files.
+        description: `Browse or search CSS classes available for slide authoring.
 
-Without 'category': returns all classes grouped by category with abbreviated declarations.
-With 'category': returns full detail for that category only.
+Three modes:
+- No args: compact table of contents (category names + class counts)
+- category: full class list with abbreviated declarations for one category
+- search: find classes by name across all categories
 
-Categories are derived from CSS file paths (e.g., "utilities/borders", "layout", "patterns").
-Use to discover available CSS classes before authoring slides. Lint catches invalid classes.`,
+Author-facing categories (layout, utilities, common components) shown by default.
+Framework-internal categories (interactions, accessibility, app shell) hidden — set includeInternal: true to include them.
+
+Use to discover available CSS classes before authoring slides. Lint catches invalid classes with fix suggestions.`,
         inputSchema: {
             type: 'object',
             properties: {
                 category: {
                     type: 'string',
-                    description: 'Optional category to get full details for (e.g., "utilities/colors", "layout", "patterns")'
+                    description: 'Get full class details for this category (e.g., "utilities/spacing", "layout", "components/cards")'
+                },
+                search: {
+                    type: 'string',
+                    description: 'Search class names (e.g., "gap", "card", "text-"). Returns matching classes with declarations.'
+                },
+                includeInternal: {
+                    type: 'boolean',
+                    description: 'Include framework-internal categories (interactions, accessibility, app shell). Default: false.'
                 }
             },
             required: []
+        },
+        annotations: {
+            readOnlyHint: true,
+            idempotentHint: true
         }
     },
     {
@@ -281,6 +323,10 @@ Use to discover available components before authoring slides.`,
                 }
             },
             required: []
+        },
+        annotations: {
+            readOnlyHint: true,
+            idempotentHint: true
         }
     },
     {
@@ -301,9 +347,12 @@ Use to discover available interactions before creating assessments.`,
                 }
             },
             required: []
+        },
+        annotations: {
+            readOnlyHint: true,
+            idempotentHint: true
         }
     },
-
     {
         name: 'coursecode_lint',
         description: `Run the course linter and get structured results.
@@ -329,6 +378,10 @@ Use AFTER making changes to validate the course.`,
             type: 'object',
             properties: {},
             required: []
+        },
+        annotations: {
+            readOnlyHint: true,
+            idempotentHint: true
         }
     },
     {
@@ -348,6 +401,10 @@ Use to discover available icons before authoring slides or configuring menus.`,
                 }
             },
             required: []
+        },
+        annotations: {
+            readOnlyHint: true,
+            idempotentHint: true
         }
     },
     {
@@ -368,6 +425,8 @@ Filtering options keep output manageable:
 - excludeInteractions: content only, no Q&A
 - format: 'md' (default) or 'json' for structured data
 
+For large courses (>40KB), full exports automatically return a summary with per-slide sizes instead. Use the slides parameter to export specific content.
+
 Does not require preview server.`,
         inputSchema: {
             type: 'object',
@@ -403,6 +462,10 @@ Does not require preview server.`,
                 }
             },
             required: []
+        },
+        annotations: {
+            readOnlyHint: true,
+            idempotentHint: true
         }
     },
 ];

package/lib/mcp-server.js

@@ -242,7 +242,7 @@ export async function startMcpServer(options = {}) {
 
                 // === Catalog & validation tools (filesystem, no preview needed) ===
                 case 'coursecode_css_catalog':
-                    result = getCssCatalog(args?.category);
+                    result = getCssCatalog(args || {});
                     break;
 
                 case 'coursecode_component_catalog':

package/lib/stub-player/outline-mode.js

@@ -41,6 +41,7 @@ export function createOutlineModeHandlers(context) {
     let isVisible = false;
     let courseLoaded = false;
     let viewingStage = null; // Which stage the dashboard is showing
+    const calloutDismissed = localStorage.getItem('coursecode-walkthroughCalloutDismissed') === 'true';
 
     async function checkStage() {
         const params = new URLSearchParams(window.location.search);
@@ -133,6 +134,9 @@ export function createOutlineModeHandlers(context) {
         // Stage stepper
         parts.push(renderStepper(detectedStage, viewingStage));
 
+        // Walkthrough callout (dismissable, shown below stepper)
+        parts.push(renderWalkthroughCallout());
+
         // Stage header — contextual button text
         const hasSlides = stageData.checklist?.hasSlides;
         let skipLabel;
@@ -511,6 +515,39 @@ export function createOutlineModeHandlers(context) {
         `;
     }
 
+    // ── Walkthrough Callout ───────────────────────────────────
+
+    function renderWalkthroughCallout() {
+        if (calloutDismissed) return '';
+
+        const hasSlides = stageData?.checklist?.hasSlides;
+        let skipLabel;
+        if (courseLoaded) {
+            skipLabel = '← Back to Course';
+        } else if (hasSlides) {
+            skipLabel = 'View Course ▸';
+        } else {
+            skipLabel = 'Skip to Course ▸';
+        }
+
+        return `
+            <div class="outline-walkthrough-callout" id="outline-walkthrough-callout">
+                <div class="outline-callout-content">
+                    <div class="outline-callout-icon">💡</div>
+                    <div class="outline-callout-text">
+                        <strong>This is an optional walkthrough.</strong>
+                        It guides you through building a course step-by-step, but you can skip it at any time.
+                        Close with the <span class="outline-callout-kbd">✕</span> in the top-right corner, or return anytime from the course preview toolbar.
+                    </div>
+                </div>
+                <div class="outline-callout-actions">
+                    <button id="outline-callout-skip-btn" class="outline-callout-skip-btn">${skipLabel}</button>
+                    <button id="outline-callout-dismiss-btn" class="outline-callout-dismiss-btn">Got it</button>
+                </div>
+            </div>
+        `;
+    }
+
     // ── Shared Components ────────────────────────────────────
 
     function renderChecklist() {
@@ -587,6 +624,17 @@ export function createOutlineModeHandlers(context) {
         // Skip / Back button
         document.getElementById('stub-player-skip-outline-btn')?.addEventListener('click', dismissDashboard);
 
+        // Walkthrough callout handlers
+        document.getElementById('outline-callout-skip-btn')?.addEventListener('click', dismissDashboard);
+        document.getElementById('outline-callout-dismiss-btn')?.addEventListener('click', () => {
+            localStorage.setItem('coursecode-walkthroughCalloutDismissed', 'true');
+            const callout = document.getElementById('outline-walkthrough-callout');
+            if (callout) {
+                callout.classList.add('dismissing');
+                callout.addEventListener('animationend', () => callout.remove(), { once: true });
+            }
+        });
+
         // Stepper clicks
         outlineContent.querySelectorAll('.stepper-step').forEach(btn => {
             btn.addEventListener('click', () => {

package/lib/stub-player/styles/_outline-mode.css

@@ -147,6 +147,116 @@
             margin-top: 20px;
         }
 
+        /* ── Walkthrough Callout ────────────────── */
+
+        .outline-walkthrough-callout {
+            margin-bottom: 24px;
+            padding: 16px 20px;
+            background: rgba(74, 111, 165, 0.1);
+            border: 1px solid rgba(74, 111, 165, 0.25);
+            border-left: 3px solid var(--color-info);
+            border-radius: 8px;
+            animation: callout-slide-in 0.3s ease-out;
+        }
+
+        @keyframes callout-slide-in {
+            from { opacity: 0; transform: translateY(-8px); }
+            to { opacity: 1; transform: translateY(0); }
+        }
+
+        .outline-walkthrough-callout.dismissing {
+            animation: callout-slide-out 0.25s ease-in forwards;
+        }
+
+        @keyframes callout-slide-out {
+            from { opacity: 1; transform: translateY(0); max-height: 200px; margin-bottom: 24px; }
+            to { opacity: 0; transform: translateY(-8px); max-height: 0; margin-bottom: 0; padding: 0 20px; overflow: hidden; }
+        }
+
+        .outline-callout-content {
+            display: flex;
+            gap: 12px;
+            align-items: flex-start;
+        }
+
+        .outline-callout-icon {
+            font-size: 20px;
+            line-height: 1;
+            flex-shrink: 0;
+            margin-top: 1px;
+        }
+
+        .outline-callout-text {
+            font-size: 13px;
+            line-height: 1.6;
+            color: var(--color-gray-400);
+        }
+
+        .outline-callout-text strong {
+            color: var(--color-white);
+        }
+
+        .outline-callout-kbd {
+            display: inline-flex;
+            align-items: center;
+            justify-content: center;
+            width: 18px;
+            height: 18px;
+            background: rgba(0, 0, 0, 0.3);
+            border: 1px solid var(--color-primary-panel);
+            border-radius: 4px;
+            font-size: 10px;
+            color: var(--color-gray-400);
+            vertical-align: middle;
+            line-height: 1;
+        }
+
+        .outline-callout-actions {
+            display: flex;
+            gap: 8px;
+            margin-top: 14px;
+            padding-left: 32px;
+        }
+
+        .outline-callout-skip-btn {
+            background: var(--color-info);
+            color: var(--color-white);
+            border: none;
+            padding: 7px 16px;
+            border-radius: 6px;
+            font-size: 12px;
+            font-weight: 600;
+            cursor: pointer;
+            transition: background 0.15s, transform 0.1s;
+        }
+
+        .outline-callout-skip-btn:hover {
+            background: color-mix(in srgb, var(--color-info) 80%, var(--color-white));
+            transform: translateY(-1px);
+        }
+
+        .outline-callout-skip-btn:active {
+            transform: translateY(0);
+        }
+
+        .outline-callout-dismiss-btn {
+            background: none;
+            color: var(--color-gray-600);
+            border: 1px solid var(--color-primary-panel);
+            padding: 7px 14px;
+            border-radius: 6px;
+            font-size: 12px;
+            font-weight: 500;
+            cursor: pointer;
+            transition: background 0.15s, color 0.15s, border-color 0.15s;
+        }
+
+        .outline-callout-dismiss-btn:hover {
+            background: var(--color-primary-panel);
+            color: var(--color-gray-200);
+            border-color: var(--color-info);
+        }
+
         /* ── Stage Header ───────────────────────── */
 
         .outline-stage-header {

package/package.json

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