@shaykec/claude-teach 0.6.2 → 0.6.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shaykec/claude-teach",
-  "version": "0.6.2",
+  "version": "0.6.4",
   "description": "Socratic AI teaching platform — learn anything through guided dialogue, visual canvas, and gamification",
   "type": "module",
   "main": "src/cli.js",
@@ -15,9 +15,9 @@
     "commander": "^12.0.0",
     "js-yaml": "^4.1.0",
     "chalk": "^5.3.0",
-    "@shaykec/bridge": "0.4.0",
-    "@shaykec/shared": "0.1.0",
-    "@shaykec/plugin": "0.2.1",
+    "@shaykec/bridge": "0.4.5",
+    "@shaykec/shared": "0.1.2",
+    "@shaykec/plugin": "0.2.11",
     "@shaykec/extension": "0.1.0"
   },
   "publishConfig": {

package/src/author.js

@@ -248,6 +248,10 @@ export async function validatePack(packPath, builtinSlugs = []) {
       // But we do check if referenced in visuals or similar.
     }
 
+    if (!existsSync(join(moduleDir, 'resources.md'))) {
+      warnings.push(`modules/${dirName}: missing resources.md — consider adding curated external links`);
+    }
+
     // XP values must be numbers
     if (mod.xp && typeof mod.xp === 'object') {
       for (const [key, val] of Object.entries(mod.xp)) {
@@ -369,10 +373,69 @@ export async function previewModule(modulePath) {
   console.log(`  To stop previewing, delete ${dest}`);
 }
 
+/* ------------------------------------------------------------------ */
+/*  Validate a single module directory                                 */
+/* ------------------------------------------------------------------ */
+
+/**
+ * Validate a single module directory (used by import command).
+ * Returns { valid, slug, errors, warnings }.
+ */
+export function validateModuleDir(moduleDir) {
+  const errors = [];
+  const warnings = [];
+
+  const moduleYamlPath = join(moduleDir, 'module.yaml');
+  if (!existsSync(moduleYamlPath)) {
+    errors.push('Missing module.yaml');
+    return { valid: false, slug: null, errors, warnings };
+  }
+
+  let mod;
+  try {
+    mod = yaml.load(readFileSync(moduleYamlPath, 'utf-8'));
+  } catch (err) {
+    errors.push(`module.yaml parse error: ${err.message}`);
+    return { valid: false, slug: null, errors, warnings };
+  }
+
+  const slug = mod.slug || basename(moduleDir);
+
+  if (!mod.slug) warnings.push('Missing "slug" field');
+  if (!mod.title) errors.push('Missing "title" field');
+  if (!mod.description) warnings.push('Missing "description" field');
+
+  if (!existsSync(join(moduleDir, 'content.md'))) {
+    errors.push('Missing content.md');
+  }
+
+  if (mod.xp && typeof mod.xp === 'object') {
+    for (const [key, val] of Object.entries(mod.xp)) {
+      if (typeof val !== 'number') {
+        errors.push(`xp.${key} must be a number, got ${typeof val}`);
+      }
+    }
+  }
+
+  if (mod.triggers !== undefined && !Array.isArray(mod.triggers)) {
+    errors.push('triggers must be an array');
+  }
+
+  if (mod.time && typeof mod.time === 'object') {
+    for (const [key, val] of Object.entries(mod.time)) {
+      if (typeof val !== 'number') {
+        errors.push(`time.${key} must be a number, got ${typeof val}`);
+      }
+    }
+  }
+
+  return { valid: errors.length === 0, slug, errors, warnings };
+}
+
 /**
  * Simple recursive directory copy (no external deps).
  */
-function copyDirRecursive(src, dest) {
+export function copyDirRecursive(src, dest) {
   mkdirSync(dest, { recursive: true });
   for (const entry of readdirSync(src, { withFileTypes: true })) {
     const srcPath = join(src, entry.name);

package/src/author.test.js

@@ -1,10 +1,165 @@
 import { describe, it, expect, beforeEach, afterEach } from 'vitest';
-import { validatePack } from './author.js';
+import { validatePack, validateModuleDir, copyDirRecursive } from './author.js';
 import fs from 'fs';
 import path from 'path';
 import os from 'os';
 import yaml from 'js-yaml';
 
+/* ================================================================== */
+/*  validateModuleDir                                                  */
+/* ================================================================== */
+
+describe('validateModuleDir', () => {
+  let tmpDir;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'teach-validate-'));
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  function createModule(meta = {}, files = {}) {
+    const defaults = {
+      slug: 'test-mod',
+      title: 'Test Module',
+      description: 'A test module',
+      category: 'test',
+      difficulty: 'beginner',
+      tags: ['test'],
+      xp: { read: 10, walkthrough: 20 },
+      time: { read: 5, guided: 15 },
+      triggers: ['how do I test?'],
+    };
+    const merged = { ...defaults, ...meta };
+    fs.writeFileSync(path.join(tmpDir, 'module.yaml'), yaml.dump(merged), 'utf-8');
+    fs.writeFileSync(path.join(tmpDir, 'content.md'), files.content || '# Test\n\nContent.\n', 'utf-8');
+
+    if (files.walkthrough) fs.writeFileSync(path.join(tmpDir, 'walkthrough.md'), files.walkthrough, 'utf-8');
+    if (files.quiz) fs.writeFileSync(path.join(tmpDir, 'quiz.md'), files.quiz, 'utf-8');
+  }
+
+  it('should pass for a valid module directory', () => {
+    createModule();
+    const result = validateModuleDir(tmpDir);
+    expect(result.valid).toBe(true);
+    expect(result.slug).toBe('test-mod');
+    expect(result.errors).toHaveLength(0);
+  });
+
+  it('should fail when module.yaml is missing', () => {
+    const result = validateModuleDir(tmpDir);
+    expect(result.valid).toBe(false);
+    expect(result.errors).toContain('Missing module.yaml');
+  });
+
+  it('should fail when content.md is missing', () => {
+    fs.writeFileSync(path.join(tmpDir, 'module.yaml'), yaml.dump({ slug: 'test', title: 'Test' }), 'utf-8');
+    const result = validateModuleDir(tmpDir);
+    expect(result.valid).toBe(false);
+    expect(result.errors).toContain('Missing content.md');
+  });
+
+  it('should fail when title is missing', () => {
+    createModule({ title: undefined });
+    const raw = yaml.load(fs.readFileSync(path.join(tmpDir, 'module.yaml'), 'utf-8'));
+    delete raw.title;
+    fs.writeFileSync(path.join(tmpDir, 'module.yaml'), yaml.dump(raw), 'utf-8');
+
+    const result = validateModuleDir(tmpDir);
+    expect(result.valid).toBe(false);
+    expect(result.errors.some(e => e.includes('title'))).toBe(true);
+  });
+
+  it('should warn when slug is missing (uses directory name fallback)', () => {
+    createModule({ slug: undefined });
+    const raw = yaml.load(fs.readFileSync(path.join(tmpDir, 'module.yaml'), 'utf-8'));
+    delete raw.slug;
+    fs.writeFileSync(path.join(tmpDir, 'module.yaml'), yaml.dump(raw), 'utf-8');
+
+    const result = validateModuleDir(tmpDir);
+    expect(result.valid).toBe(true);
+    expect(result.warnings.some(w => w.includes('slug'))).toBe(true);
+    expect(result.slug).toBe(path.basename(tmpDir));
+  });
+
+  it('should fail when xp values are not numbers', () => {
+    createModule({ xp: { read: 'ten' } });
+    const result = validateModuleDir(tmpDir);
+    expect(result.valid).toBe(false);
+    expect(result.errors.some(e => e.includes('xp.read'))).toBe(true);
+  });
+
+  it('should fail when triggers is not an array', () => {
+    createModule({ triggers: 'not an array' });
+    const result = validateModuleDir(tmpDir);
+    expect(result.valid).toBe(false);
+    expect(result.errors.some(e => e.includes('triggers'))).toBe(true);
+  });
+
+  it('should fail when time values are not numbers', () => {
+    createModule({ time: { read: 'five' } });
+    const result = validateModuleDir(tmpDir);
+    expect(result.valid).toBe(false);
+    expect(result.errors.some(e => e.includes('time.read'))).toBe(true);
+  });
+});
+
+/* ================================================================== */
+/*  copyDirRecursive                                                   */
+/* ================================================================== */
+
+describe('copyDirRecursive', () => {
+  let srcDir;
+  let destDir;
+
+  beforeEach(() => {
+    srcDir = fs.mkdtempSync(path.join(os.tmpdir(), 'teach-copy-src-'));
+    destDir = path.join(os.tmpdir(), `teach-copy-dest-${Date.now()}`);
+  });
+
+  afterEach(() => {
+    fs.rmSync(srcDir, { recursive: true, force: true });
+    if (fs.existsSync(destDir)) fs.rmSync(destDir, { recursive: true, force: true });
+  });
+
+  it('should copy all files from source to destination', () => {
+    fs.writeFileSync(path.join(srcDir, 'module.yaml'), 'slug: test\n', 'utf-8');
+    fs.writeFileSync(path.join(srcDir, 'content.md'), '# Content\n', 'utf-8');
+
+    copyDirRecursive(srcDir, destDir);
+
+    expect(fs.existsSync(path.join(destDir, 'module.yaml'))).toBe(true);
+    expect(fs.existsSync(path.join(destDir, 'content.md'))).toBe(true);
+    expect(fs.readFileSync(path.join(destDir, 'module.yaml'), 'utf-8')).toBe('slug: test\n');
+  });
+
+  it('should copy nested directories recursively', () => {
+    fs.mkdirSync(path.join(srcDir, 'sub'), { recursive: true });
+    fs.writeFileSync(path.join(srcDir, 'top.txt'), 'top', 'utf-8');
+    fs.writeFileSync(path.join(srcDir, 'sub', 'nested.txt'), 'nested', 'utf-8');
+
+    copyDirRecursive(srcDir, destDir);
+
+    expect(fs.existsSync(path.join(destDir, 'top.txt'))).toBe(true);
+    expect(fs.existsSync(path.join(destDir, 'sub', 'nested.txt'))).toBe(true);
+    expect(fs.readFileSync(path.join(destDir, 'sub', 'nested.txt'), 'utf-8')).toBe('nested');
+  });
+
+  it('should create destination directory if it does not exist', () => {
+    fs.writeFileSync(path.join(srcDir, 'file.txt'), 'data', 'utf-8');
+
+    expect(fs.existsSync(destDir)).toBe(false);
+    copyDirRecursive(srcDir, destDir);
+    expect(fs.existsSync(destDir)).toBe(true);
+  });
+});
+
+/* ================================================================== */
+/*  validatePack — media validation                                    */
+/* ================================================================== */
+
 describe('validatePack — media validation', () => {
   let tmpDir;
 
@@ -71,7 +226,7 @@ describe('validatePack — media validation', () => {
     expect(result.valid).toBe(true);
     expect(result.errors).toHaveLength(0);
     // No warnings for properly filled media entries
-    const mediaWarnings = result.warnings.filter(w => w.includes('media'));
+    const mediaWarnings = result.warnings.filter(w => w.includes('media['));
     expect(mediaWarnings).toHaveLength(0);
   });
 

package/src/cli.js

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 
 import { Command } from 'commander';
-import { readFileSync, existsSync } from 'fs';
-import { resolve, join, dirname } from 'path';
+import { readFileSync, existsSync, mkdirSync } from 'fs';
+import { resolve, join, basename, dirname } from 'path';
 import { fileURLToPath } from 'url';
 import { exec, spawn, execFileSync as execFileSyncChild } from 'child_process';
 import { createRequire } from 'module';
@@ -74,6 +74,20 @@ function openExtensionInstall(extensionDir) {
   }
 }
 
+/** Kill any process listening on a given port. Returns true if something was killed. */
+function killPort(port) {
+  try {
+    const pids = execFileSyncChild('lsof', ['-ti', `:${port}`], { encoding: 'utf-8' }).trim();
+    if (pids) {
+      for (const pid of pids.split('\n')) {
+        try { process.kill(parseInt(pid, 10), 'SIGTERM'); } catch {}
+      }
+      return true;
+    }
+  } catch {}
+  return false;
+}
+
 /** Open a URL in the default browser (cross-platform). */
 function openUrl(url) {
   const platform = process.platform;
@@ -102,6 +116,9 @@ Examples:
   $ claude-teach stats                          View your XP and belt progress
   $ claude-teach install user/my-pack           Install a module pack from GitHub
   $ claude-teach search docker                  Search registries for packs
+  $ claude-teach learn "google sheets"          Generate a module on any topic
+  $ claude-teach export git --to ~/Desktop      Export a module for sharing
+  $ claude-teach import ~/Desktop/my-module     Import a shared module
   $ claude-teach author init my-pack            Scaffold a new module pack
   $ claude-teach author validate ./my-pack      Validate a pack
   $ claude-teach start                          Launch Claude Code with teaching skills
@@ -122,7 +139,7 @@ program
   .option('-c, --category <category>', 'Filter by category')
   .option('-d, --difficulty <level>', 'Filter by difficulty (beginner|intermediate|advanced)')
   .option('-t, --tag <tag>', 'Filter by tag')
-  .option('-s, --source <source>', 'Filter by source (built-in|pack:<name>|local)')
+  .option('-s, --source <source>', 'Filter by source (built-in|pack:<name>|local|generated)')
   .action(async (opts) => {
     const registry = await loadRegistry(ROOT);
     let modules = registry.modules;
@@ -257,6 +274,122 @@ program
     console.log(suggestion);
   });
 
+// --- learn (free-style) ---
+program
+  .command('learn <topic>')
+  .description('Generate an AI learning module on any topic (saved to ~/.claude-teach/modules/local/_generated/)')
+  .action(async (topic) => {
+    const { GENERATED_MODULES, ensureHome } = await import('./marketplace.js');
+    ensureHome();
+
+    const slug = topic
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, '-')
+      .replace(/^-+|-+$/g, '');
+
+    const moduleDir = join(GENERATED_MODULES, slug);
+    if (!existsSync(GENERATED_MODULES)) {
+      mkdirSync(GENERATED_MODULES, { recursive: true });
+    }
+
+    if (existsSync(moduleDir)) {
+      console.log(chalk.yellow(`Module "${slug}" already exists at ${moduleDir}`));
+      console.log(`  Use ${chalk.cyan(`/teach:learn ${slug} --regenerate`)} to recreate it.`);
+      console.log(`  Or ${chalk.cyan(`/teach ${slug}`)} to start learning.`);
+      return;
+    }
+
+    mkdirSync(moduleDir, { recursive: true });
+    console.log(chalk.green(`Created module directory: ${moduleDir}`));
+    console.log(`\n  Use ${chalk.cyan(`/teach:learn ${topic}`)} in Claude Code to generate content and start learning.`);
+    console.log(`  Or author the module files manually in: ${chalk.dim(moduleDir)}`);
+  });
+
+// =====================================================================
+//  Sharing commands — export and import modules
+// =====================================================================
+
+// --- export ---
+program
+  .command('export <slug>')
+  .description('Export a module directory (copy to current directory or --to <path>)')
+  .option('--to <path>', 'Target directory', '.')
+  .action(async (slug, opts) => {
+    const registry = await loadRegistry(ROOT);
+    const mod = getModule(registry, slug);
+    if (!mod) {
+      console.error(chalk.red(`Module "${slug}" not found. Run "claude-teach list" to see available modules.`));
+      process.exit(1);
+    }
+
+    const { copyDirRecursive } = await import('./author.js');
+    const dest = resolve(process.cwd(), opts.to, slug);
+
+    if (existsSync(dest)) {
+      console.error(chalk.red(`Destination "${dest}" already exists. Remove it first or choose a different path.`));
+      process.exit(1);
+    }
+
+    copyDirRecursive(mod._path, dest);
+    console.log(chalk.green(`Exported "${slug}" to ${dest}`));
+    console.log(`  Source: ${chalk.dim(mod.source)}`);
+    console.log(`  Files: module.yaml, content.md, ${mod.capabilities.filter(c => c !== 'content').join('.md, ')}.md`);
+  });
+
+// --- import ---
+program
+  .command('import <path>')
+  .description('Import a module directory into local modules')
+  .action(async (modulePath) => {
+    const absPath = resolve(process.cwd(), modulePath);
+
+    if (!existsSync(absPath)) {
+      console.error(chalk.red(`Path "${absPath}" does not exist.`));
+      process.exit(1);
+    }
+
+    const { validateModuleDir, copyDirRecursive } = await import('./author.js');
+    const result = validateModuleDir(absPath);
+
+    if (!result.valid) {
+      console.error(chalk.red(`\n  Validation errors:\n`));
+      for (const err of result.errors) {
+        console.error(`  ${chalk.red('✗')} ${err}`);
+      }
+      process.exit(1);
+    }
+
+    if (result.warnings.length > 0) {
+      for (const warn of result.warnings) {
+        console.log(`  ${chalk.yellow('!')} ${warn}`);
+      }
+    }
+
+    const { LOCAL_MODULES, ensureHome } = await import('./marketplace.js');
+    ensureHome();
+
+    const slug = result.slug;
+    const dest = join(LOCAL_MODULES, slug);
+
+    const registry = await loadRegistry(ROOT);
+    const existing = getModule(registry, slug);
+    if (existing) {
+      console.warn(chalk.yellow(`  Warning: slug "${slug}" collides with existing module (${existing.source}).`));
+      console.warn(`  The imported module will be placed in local/ and may not override the existing one.`);
+    }
+
+    if (existsSync(dest)) {
+      console.error(chalk.red(`Local module "${slug}" already exists at ${dest}. Remove it first.`));
+      process.exit(1);
+    }
+
+    copyDirRecursive(absPath, dest);
+
+    await buildRegistry(ROOT);
+    console.log(chalk.green(`Imported "${slug}" to ${dest}`));
+    console.log(`  Run ${chalk.cyan(`claude-teach get ${slug}`)} or ${chalk.cyan(`/teach ${slug}`)} to start learning.`);
+  });
+
 // =====================================================================
 //  Visual Ecosystem commands
 // =====================================================================
@@ -267,10 +400,15 @@ program
   .description('Start the bridge server for visual canvas — diagrams, quizzes, dashboard (default port: 3456)')
   .option('-p, --port <port>', 'Port number', '3456')
   .action(async (opts) => {
+    const port = parseInt(opts.port, 10);
+    if (killPort(port)) {
+      console.log(chalk.dim(`  Killed old process on port ${port}`));
+      await new Promise(r => setTimeout(r, 500));
+    }
     const { startServer } = await import('@shaykec/bridge');
     const progress = loadProgress(ROOT);
     startServer({
-      port: parseInt(opts.port, 10),
+      port,
       progressProvider: {
         getProgress: () => loadProgress(ROOT),
       },
@@ -325,6 +463,10 @@ program
       try {
         const { startServer } = await import('@shaykec/bridge');
         const port = parseInt(opts.port, 10);
+        if (killPort(port)) {
+          console.log(chalk.dim(`  Killed old bridge on port ${port}`));
+          await new Promise(r => setTimeout(r, 500));
+        }
         server = await new Promise((resolve, reject) => {
           const srv = startServer({
             port,

package/src/marketplace.js

@@ -19,6 +19,7 @@ import chalk from 'chalk';
 const TEACH_HOME = join(homedir(), '.claude-teach');
 const MODULES_HOME = join(TEACH_HOME, 'modules');
 const LOCAL_MODULES = join(MODULES_HOME, 'local');
+const GENERATED_MODULES = join(LOCAL_MODULES, '_generated');
 const CONFIG_PATH = join(TEACH_HOME, 'config.yaml');
 
 const DEFAULT_REGISTRY = {
@@ -346,4 +347,4 @@ export function removeRegistry(nameOrUrl) {
 /*  Exports for registry.js integration                                */
 /* ------------------------------------------------------------------ */
 
-export { TEACH_HOME, MODULES_HOME, LOCAL_MODULES };
+export { TEACH_HOME, MODULES_HOME, LOCAL_MODULES, GENERATED_MODULES };

package/src/registry.js

@@ -1,18 +1,21 @@
 /**
- * Module registry — discovers module.yaml files from three sources and builds
+ * Module registry — discovers module.yaml files from four sources and builds
  * a unified searchable index.
  *
- * Sources:
+ * Sources (priority order — highest first):
+ *   0. Generated  — ~/.claude-teach/modules/local/_generated/ (AI-generated, fork-on-write)
  *   1. Built-in   — packages/modules/           (ships with ClaudeTeach)
  *   2. Packs      — ~/.claude-teach/modules/<pack>/modules/  (installed via git)
  *   3. Local      — ~/.claude-teach/modules/local/           (user-authored)
+ *
+ * Generated modules override any source on slug collision (fork-on-write priority).
  */
 
 import { readFileSync, writeFileSync, existsSync, readdirSync, statSync } from 'fs';
 import { join, resolve } from 'path';
 import yaml from 'js-yaml';
 import chalk from 'chalk';
-import { MODULES_HOME, LOCAL_MODULES, ensureHome } from './marketplace.js';
+import { MODULES_HOME, LOCAL_MODULES, GENERATED_MODULES, ensureHome } from './marketplace.js';
 
 const BUILTIN_MODULES_DIR = 'packages/modules';
 const REGISTRY_FILE = 'registry.yaml';
@@ -83,23 +86,35 @@ function toRegistryEntry({ meta, modulePath, dirName }, source) {
 /* ------------------------------------------------------------------ */
 
 /**
- * Scan all three module sources and build a merged registry.
- * Built-in modules win on slug collisions.
+ * Scan all four module sources and build a merged registry.
+ * Generated modules (fork-on-write) have highest priority and override
+ * any other source on slug collision. All other sources use first-wins.
  */
 export async function buildRegistry(rootDir) {
-  const slugMap = new Map(); // slug -> entry (first-seen wins)
+  const slugMap = new Map(); // slug -> entry
   const allModules = [];
 
+  // --- 0. AI-generated modules (highest priority — fork-on-write overrides) ---
+  ensureHome();
+  if (existsSync(GENERATED_MODULES)) {
+    for (const item of scanModuleDir(GENERATED_MODULES)) {
+      const entry = toRegistryEntry(item, 'generated');
+      if (item.meta.forkedFrom) entry.forkedFrom = item.meta.forkedFrom;
+      slugMap.set(entry.slug, entry);
+      allModules.push(entry);
+    }
+  }
+
   // --- 1. Built-in modules ---
   const builtinDir = resolve(rootDir, BUILTIN_MODULES_DIR);
   for (const item of scanModuleDir(builtinDir)) {
     const entry = toRegistryEntry(item, 'built-in');
+    if (slugMap.has(entry.slug)) continue; // generated fork takes priority
     slugMap.set(entry.slug, entry);
     allModules.push(entry);
   }
 
   // --- 2. Installed packs ---
-  ensureHome();
   if (existsSync(MODULES_HOME)) {
     for (const packDir of readdirSync(MODULES_HOME)) {
       if (packDir === 'local') continue;
@@ -107,9 +122,11 @@ export async function buildRegistry(rootDir) {
       for (const item of scanModuleDir(packModulesDir)) {
         const entry = toRegistryEntry(item, `pack:${packDir}`);
         if (slugMap.has(entry.slug)) {
-          console.warn(
-            chalk.yellow(`  Warning: slug "${entry.slug}" from pack "${packDir}" collides with ${slugMap.get(entry.slug).source} — skipping.`)
-          );
+          if (slugMap.get(entry.slug).source !== 'generated') {
+            console.warn(
+              chalk.yellow(`  Warning: slug "${entry.slug}" from pack "${packDir}" collides with ${slugMap.get(entry.slug).source} — skipping.`)
+            );
+          }
           continue;
         }
         slugMap.set(entry.slug, entry);
@@ -120,13 +137,14 @@ export async function buildRegistry(rootDir) {
 
   // --- 3. Local custom modules ---
   if (existsSync(LOCAL_MODULES)) {
-    // Scan top-level directories inside local/
     for (const item of scanModuleDir(LOCAL_MODULES)) {
       const entry = toRegistryEntry(item, 'local');
       if (slugMap.has(entry.slug)) {
-        console.warn(
-          chalk.yellow(`  Warning: local slug "${entry.slug}" collides with ${slugMap.get(entry.slug).source} — skipping.`)
-        );
+        if (slugMap.get(entry.slug).source !== 'generated') {
+          console.warn(
+            chalk.yellow(`  Warning: local slug "${entry.slug}" collides with ${slugMap.get(entry.slug).source} — skipping.`)
+          );
+        }
         continue;
       }
       slugMap.set(entry.slug, entry);
@@ -139,9 +157,11 @@ export async function buildRegistry(rootDir) {
       for (const item of scanModuleDir(previewDir)) {
         const entry = toRegistryEntry(item, 'local');
         if (slugMap.has(entry.slug)) {
-          console.warn(
-            chalk.yellow(`  Warning: preview slug "${entry.slug}" collides with ${slugMap.get(entry.slug).source} — skipping.`)
-          );
+          if (slugMap.get(entry.slug).source !== 'generated') {
+            console.warn(
+              chalk.yellow(`  Warning: preview slug "${entry.slug}" collides with ${slugMap.get(entry.slug).source} — skipping.`)
+            );
+          }
           continue;
         }
         slugMap.set(entry.slug, entry);

package/src/registry.test.js

@@ -1,4 +1,4 @@
-import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
 import { getModule } from './registry.js';
 import fs from 'fs';
 import path from 'path';
@@ -101,7 +101,7 @@ describe('Registry entry structure', () => {
 
   it('each entry should have a source field', () => {
     expect(typeof sampleEntry.source).toBe('string');
-    expect(['built-in', 'local'].includes(sampleEntry.source) || sampleEntry.source.startsWith('pack:')).toBe(true);
+    expect(['built-in', 'local', 'generated'].includes(sampleEntry.source) || sampleEntry.source.startsWith('pack:')).toBe(true);
   });
 
   it('each entry should have a capabilities array', () => {
@@ -362,3 +362,88 @@ describe('buildRegistry (filesystem)', () => {
     expect(slugs).not.toContain('no-yaml');
   });
 });
+
+/* ================================================================== */
+/*  Generated modules (_generated/ directory)                          */
+/*  Uses the real GENERATED_MODULES path with unique test slugs.       */
+/* ================================================================== */
+
+describe('buildRegistry — generated modules', () => {
+  const ROOT = path.resolve(path.dirname(new URL(import.meta.url).pathname), '..', '..', '..');
+  const testSlugs = [];
+  let genDir;
+
+  beforeEach(async () => {
+    const { GENERATED_MODULES, ensureHome } = await import('./marketplace.js');
+    ensureHome();
+    genDir = GENERATED_MODULES;
+    if (!fs.existsSync(genDir)) fs.mkdirSync(genDir, { recursive: true });
+  });
+
+  afterEach(() => {
+    for (const slug of testSlugs) {
+      const dir = path.join(genDir, slug);
+      if (fs.existsSync(dir)) fs.rmSync(dir, { recursive: true, force: true });
+    }
+    testSlugs.length = 0;
+  });
+
+  function createGeneratedModule(slug, meta = {}) {
+    testSlugs.push(slug);
+    const moduleDir = path.join(genDir, slug);
+    fs.mkdirSync(moduleDir, { recursive: true });
+    const defaults = {
+      slug, title: `Generated ${slug}`, description: `AI-generated ${slug}`,
+      category: 'test', difficulty: 'beginner', tags: [],
+      xp: { read: 10 }, time: { read: 5 }, prerequisites: [], related: [], triggers: [],
+    };
+    fs.writeFileSync(path.join(moduleDir, 'module.yaml'), yaml.dump({ ...defaults, ...meta }), 'utf-8');
+    fs.writeFileSync(path.join(moduleDir, 'content.md'), `# ${slug}\n`, 'utf-8');
+    return moduleDir;
+  }
+
+  it('should discover generated modules with source "generated"', async () => {
+    createGeneratedModule('_test-gen-discover');
+
+    const { buildRegistry } = await import('./registry.js');
+    const registry = await buildRegistry(ROOT);
+
+    const mod = registry.modules.find(m => m.slug === '_test-gen-discover');
+    expect(mod).toBeDefined();
+    expect(mod.source).toBe('generated');
+  });
+
+  it('generated modules should override built-in modules with same slug', async () => {
+    createGeneratedModule('git', { title: 'Git Customized', description: 'Forked version', forkedFrom: 'built-in' });
+
+    const { buildRegistry } = await import('./registry.js');
+    const registry = await buildRegistry(ROOT);
+
+    const gitModules = registry.modules.filter(m => m.slug === 'git');
+    expect(gitModules).toHaveLength(1);
+    expect(gitModules[0].source).toBe('generated');
+    expect(gitModules[0].title).toBe('Git Customized');
+  });
+
+  it('should preserve forkedFrom field from module.yaml', async () => {
+    createGeneratedModule('_test-gen-forked', { forkedFrom: 'built-in' });
+
+    const { buildRegistry } = await import('./registry.js');
+    const registry = await buildRegistry(ROOT);
+
+    const mod = registry.modules.find(m => m.slug === '_test-gen-forked');
+    expect(mod).toBeDefined();
+    expect(mod.forkedFrom).toBe('built-in');
+  });
+
+  it('generated and built-in modules should coexist when slugs differ', async () => {
+    createGeneratedModule('_test-gen-coexist');
+
+    const { buildRegistry } = await import('./registry.js');
+    const registry = await buildRegistry(ROOT);
+
+    const slugs = registry.modules.map(m => m.slug);
+    expect(slugs).toContain('git'); // built-in
+    expect(slugs).toContain('_test-gen-coexist'); // generated
+  });
+});