claudecode-omc 5.4.0 → 5.5.1

package/src/cli/artifact.js

@@ -11,6 +11,19 @@ const { loadAgentsFromSource } = require('../merge/agent-merger');
 const { loadCommandsFromSource } = require('../merge/command-merger');
 const { loadHookFilesFromSource } = require('../merge/hook-merger');
 const { loadFilesFromSource } = require('../merge/file-merger');
+const { loadClaudeMd } = require('../merge/claude-md-merger');
+
+function loadSectionDocumentFromSource(sourceDir) {
+  const content = loadClaudeMd(sourceDir);
+  if (!content) return [];
+  return [{
+    name: 'CLAUDE.md',
+    path: sourceDir,
+    metadata: {
+      description: `${content.length} chars of prompt guidelines`,
+    },
+  }];
+}
 
 function getLoader(artifactType) {
   switch (artifactType) {
@@ -18,6 +31,8 @@ function getLoader(artifactType) {
     case 'agents': return loadAgentsFromSource;
     case 'commands': return loadCommandsFromSource;
     case 'hooks': return loadHookFilesFromSource;
+    case 'guidelines': return loadSectionDocumentFromSource;
+    case 'claude-md': return loadSectionDocumentFromSource;
     case 'hud': return loadFilesFromSource;
     default: return null;
   }
@@ -42,6 +57,11 @@ function loadSourcesForType(artifactType, root) {
       sources.push({ name, items });
     }
   }
+
+  if (sources.length === 0 && artifactType === 'claude-md') {
+    return loadSourcesForType('guidelines', root);
+  }
+
   return sources;
 }
 
@@ -62,6 +82,23 @@ async function artifact(args, flags = {}) {
         return;
       }
 
+      const artifactConfig = ARTIFACT_TYPES[artifactType];
+      if (artifactConfig.mergeStrategy === 'section-concat') {
+        const total = sources.reduce((sum, source) => sum + source.items.length, 0);
+        console.log(`${artifactConfig.label} (${total} installable, additive merge, from ${sources.length} sources):`);
+        console.log('');
+
+        for (const source of sources) {
+          console.log(`[${source.name}] (${source.items.length})`);
+          for (const item of source.items) {
+            const desc = item.metadata?.description || '';
+            console.log(`  ${item.name}${desc ? ' — ' + desc : ''}`);
+          }
+          console.log('');
+        }
+        return;
+      }
+
       const mergeConfigPath = getMergeConfigPath(root);
       let mergeConfig = { preferences: {} };
       if (fs.existsSync(mergeConfigPath)) {
@@ -109,6 +146,9 @@ async function artifact(args, flags = {}) {
     }
 
     case 'prefer': {
+      if (ARTIFACT_TYPES[artifactType].mergeStrategy === 'section-concat') {
+        throw new Error(`${artifactType} is merged additively and does not support source preferences.`);
+      }
       const name = args[1];
       const source = args[2];
       if (!name || !source) {
@@ -126,6 +166,13 @@ async function artifact(args, flags = {}) {
     }
 
     case 'conflicts': {
+      if (ARTIFACT_TYPES[artifactType].mergeStrategy === 'section-concat') {
+        console.log(`${ARTIFACT_TYPES[artifactType].label} Conflict Report`);
+        console.log('='.repeat(40));
+        console.log('Section-concat artifacts are merged additively; no conflicts to resolve.');
+        return;
+      }
+
       const sources = loadSourcesForType(artifactType, root);
       if (sources.length < 2) {
         console.log(`Need at least 2 sources for ${artifactType}. Run: omc-manage source sync`);

package/src/cli/doctor.js

@@ -71,7 +71,12 @@ async function doctor() {
   console.log('');
 
   console.log('Installation:');
-  for (const typeName of getArtifactTypeNames()) {
+  const typeNames = getArtifactTypeNames().filter(typeName => {
+    if (typeName !== 'claude-md') return true;
+    return !fs.existsSync(ARTIFACT_TYPES.guidelines.installTarget);
+  });
+
+  for (const typeName of typeNames) {
     const type = ARTIFACT_TYPES[typeName];
     const target = type.installTarget;
     if (fs.existsSync(target)) {

package/src/cli/guidelines.js

@@ -0,0 +1,83 @@
+/* eslint-disable no-console */
+const path = require('path');
+const { optimizeGuidelines } = require('../guidelines/optimizer');
+const { applyGuidelineResult } = require('../guidelines/apply');
+
+async function guidelines(args, flags = {}) {
+  const cmd = args[0] || 'help';
+
+  switch (cmd) {
+    case 'optimize': {
+      const selectedSources = args.slice(1);
+      const result = await optimizeGuidelines({
+        sources: selectedSources,
+        outputDir: flags.outputDir,
+        dryRun: flags.dryRun,
+      });
+
+      const { summary } = result;
+      console.log('Guidelines Optimization');
+      console.log('=======================');
+      console.log(`Sources: ${summary.sourceCount}`);
+      console.log(`Sections: ${summary.sectionCount}`);
+      console.log(`Target runtime file: ${summary.outputPath}`);
+
+      if (flags.dryRun) {
+        console.log('');
+        console.log('[dry-run] Would write maintainer artifacts to:');
+        console.log(`  latest: ${summary.latestDir}`);
+        console.log(`  run:    ${summary.runDir}`);
+      } else {
+        console.log('');
+        console.log('Wrote maintainer artifacts:');
+        console.log(`  latest: ${summary.latestDir}`);
+        console.log(`  run:    ${summary.runDir}`);
+        console.log('');
+        console.log('Next step for Claude Code CLI or Codex:');
+        console.log(`  read ${path.join(summary.latestDir, 'next-steps.md')}`);
+      }
+
+      break;
+    }
+
+    case 'apply': {
+      const result = await applyGuidelineResult({
+        resultFile: flags.resultFile || args[1],
+        outputDir: flags.outputDir,
+        dryRun: flags.dryRun,
+      });
+
+      console.log('Guidelines Apply');
+      console.log('================');
+      console.log(`Result file: ${result.resultFile}`);
+      console.log(`Runtime file: ${result.runtimePath}`);
+
+      if (flags.dryRun) {
+        console.log('');
+        console.log('[dry-run] Would write:');
+        console.log(`  ${path.join(result.latestDir, 'result.json')}`);
+        console.log(`  ${path.join(result.latestDir, 'decision-log.md')}`);
+        console.log(`  ${result.runtimePath}`);
+      } else {
+        console.log('');
+        console.log('Wrote:');
+        console.log(`  ${path.join(result.latestDir, 'result.json')}`);
+        console.log(`  ${path.join(result.latestDir, 'decision-log.md')}`);
+        console.log(`  ${result.runtimePath}`);
+      }
+
+      break;
+    }
+
+    case 'help':
+    default:
+      console.log('Usage:');
+      console.log('  omc-manage guidelines optimize [source...] [--output-dir <dir>] [--dry-run]');
+      console.log('  omc-manage guidelines apply --result-file <path> [--output-dir <dir>] [--dry-run]');
+      console.log('');
+      console.log('Build or apply maintainer-only guideline optimization artifacts.');
+      console.log('The optimizer skill is repository-only and is not installed into user Claude Code configs.');
+  }
+}
+
+module.exports = { guidelines };

package/src/cli/index.js

@@ -6,6 +6,7 @@ const COMMANDS = {
   source: () => require('./source'),
   skill: () => require('./skill'),
   artifact: () => require('./artifact'),
+  guidelines: () => require('./guidelines'),
 };
 
 function showHelp() {
@@ -19,13 +20,16 @@ function showHelp() {
   console.log('  doctor    Health checks for all artifact types');
   console.log('  source    list|add|remove|sync|status — manage sources');
   console.log('  artifact  list|prefer|conflicts [--type <type>] — manage artifacts');
+  console.log('  guidelines optimize [source...] [--output-dir <dir>] [--dry-run]');
+  console.log('  guidelines apply --result-file <path> [--output-dir <dir>] [--dry-run]');
+  console.log('            Build or apply maintainer guideline optimization artifacts');
   console.log('  skill     list|prefer|conflicts — alias for artifact --type skills');
   console.log('            evaluate [name] — quality score (Anthropic-aligned)');
   console.log('            compare [--threshold N] — cross-source overlap analysis');
   console.log('            recommend [--apply] — preference recommendations');
   console.log('  help      Show this help');
   console.log('');
-  console.log('Artifact types: skills, agents, hooks, commands, claude-md, settings, hud');
+  console.log('Artifact types: skills, agents, hooks, commands, guidelines, claude-md, settings, hud');
 }
 
 async function main(argv) {
@@ -71,6 +75,14 @@ async function main(argv) {
     else if (arg === '--ref' && args[i + 1]) flags.ref = args[++i];
     else if (arg === '--priority' && args[i + 1]) flags.priority = parseInt(args[++i], 10);
     else if (arg === '--artifacts' && args[i + 1]) flags.artifacts = args[++i].split(',');
+    else if (arg === '--mapping' && args[i + 1]) flags.mapping = args[++i];
+    else if (arg.startsWith('--mapping=')) flags.mapping = arg.split('=')[1];
+    else if (arg === '--role' && args[i + 1]) flags.role = args[++i];
+    else if (arg.startsWith('--role=')) flags.role = arg.split('=')[1];
+    else if (arg === '--output-dir' && args[i + 1]) flags.outputDir = args[++i];
+    else if (arg.startsWith('--output-dir=')) flags.outputDir = arg.split('=')[1];
+    else if (arg === '--result-file' && args[i + 1]) flags.resultFile = args[++i];
+    else if (arg.startsWith('--result-file=')) flags.resultFile = arg.split('=')[1];
     else if (arg === '--apply') flags.apply = true;
     else if (arg === '--threshold' && args[i + 1]) flags.threshold = args[++i];
     else if (arg.startsWith('--threshold=')) flags.threshold = arg.split('=')[1];

package/src/cli/setup.js

@@ -2,6 +2,7 @@
 const fs = require('fs');
 const fsp = require('fs/promises');
 const path = require('path');
+const os = require('os');
 const { getProjectRoot, getSourceArtifactDir, getInstallTarget, getMergeConfigPath, getReportDir } = require('../config/paths');
 const { readConfig } = require('../config/sources');
 const { getArtifactTypeNames, ARTIFACT_TYPES } = require('../config/artifact-types');
@@ -16,6 +17,30 @@ const { loadFilesFromSource } = require('../merge/file-merger');
 const { evaluateSkillQuality } = require('../utils/quality');
 const { copyDirRecursive } = require('./source');
 
+const OMC_VERSION_PATH = path.join(os.homedir(), '.claude', '.omc-version.json');
+
+function getPackageVersion(root) {
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8'));
+    return pkg.version || '0.0.0';
+  } catch {
+    return '0.0.0';
+  }
+}
+
+async function writeInstallMetadata(root) {
+  const now = new Date().toISOString();
+  const metadata = {
+    version: getPackageVersion(root),
+    installedAt: now,
+    installMethod: fs.existsSync(path.join(root, '.git')) ? 'local-dev' : 'npm',
+    lastCheckAt: now,
+  };
+
+  await fsp.mkdir(path.dirname(OMC_VERSION_PATH), { recursive: true });
+  await fsp.writeFile(OMC_VERSION_PATH, JSON.stringify(metadata, null, 2) + '\n', 'utf8');
+}
+
 async function copyDirectory(src, dest, options = {}) {
   if (!fs.existsSync(src)) return 0;
   if (!options.dryRun) await fsp.mkdir(dest, { recursive: true });
@@ -49,6 +74,29 @@ function getLoader(artifactType) {
   }
 }
 
+function collectSourcesForType(artifactType, orderedSources, root) {
+  const sourcesForType = [];
+
+  for (const [name, src] of orderedSources) {
+    // Skip reference-only sources (e.g. anthropic-skills) — they provide
+    // evaluation standards, not installable artifacts.
+    if (src.role === 'reference') continue;
+    const declaredArtifacts = src.artifacts || [];
+    if (!declaredArtifacts.includes(artifactType)) continue;
+
+    const dir = getSourceArtifactDir(name, artifactType, root);
+    if (fs.existsSync(dir)) {
+      sourcesForType.push({ name, dir, priority: src.priority });
+    }
+  }
+
+  if (sourcesForType.length === 0 && artifactType === 'claude-md') {
+    return collectSourcesForType('guidelines', orderedSources, root);
+  }
+
+  return sourcesForType;
+}
+
 async function installNameBasedArtifacts(artifactType, sources, mergeConfig, installTarget, flags) {
   const loader = getLoader(artifactType);
   if (!loader) return { count: 0, total: 0 };
@@ -137,7 +185,7 @@ async function installHooks(sources, installTarget, flags) {
   return result;
 }
 
-async function installClaudeMd(sources, installTarget, flags) {
+async function installSectionDocument(artifactType, sources, installTarget, flags) {
   const sections = [];
   // Collect in reverse priority order (lowest priority first)
   const sorted = [...sources].reverse();
@@ -159,7 +207,15 @@ async function installClaudeMd(sources, installTarget, flags) {
   let finalContent;
   if (fs.existsSync(installTarget)) {
     const existing = fs.readFileSync(installTarget, 'utf8');
-    finalContent = mergeIntoExisting(existing, sections);
+    finalContent = mergeIntoExisting(existing, sections, {
+      markerNamespace: artifactType,
+      legacyMarkerKeys: (sourceName) => {
+        if (artifactType === 'guidelines') {
+          return [sourceName, `claude-md:${sourceName}`];
+        }
+        return [sourceName];
+      },
+    });
   } else {
     finalContent = assembleSections(sections);
   }
@@ -206,7 +262,9 @@ async function setup(args, flags = {}) {
   const root = getProjectRoot();
   const config = readConfig();
   const scope = flags.scope || 'user';
-  const typeFilter = flags.type ? flags.type.split(',') : null;
+  const typeFilter = flags.type
+    ? [...new Set(flags.type.split(',').map(type => (type === 'claude-md' ? 'guidelines' : type)))]
+    : null;
 
   console.log('claudecode-omc setup');
   console.log('====================');
@@ -225,7 +283,7 @@ async function setup(args, flags = {}) {
   const orderedSources = Object.entries(config.sources)
     .sort(([, a], [, b]) => a.priority - b.priority);
 
-  const allTypes = getArtifactTypeNames();
+  const allTypes = getArtifactTypeNames().filter(type => type !== 'claude-md');
   const typesToInstall = typeFilter || allTypes;
   let step = 0;
   const totalSteps = typesToInstall.length;
@@ -238,20 +296,7 @@ async function setup(args, flags = {}) {
       continue;
     }
 
-    // Collect sources that have this artifact type
-    const sourcesForType = [];
-    for (const [name, src] of orderedSources) {
-      // Skip reference-only sources (e.g. anthropic-skills) — they provide
-      // evaluation standards, not installable artifacts.
-      if (src.role === 'reference') continue;
-      const declaredArtifacts = src.artifacts || [];
-      if (!declaredArtifacts.includes(artifactType)) continue;
-
-      const dir = getSourceArtifactDir(name, artifactType, root);
-      if (fs.existsSync(dir)) {
-        sourcesForType.push({ name, dir, priority: src.priority });
-      }
-    }
+    const sourcesForType = collectSourcesForType(artifactType, orderedSources, root);
 
     const installTarget = (artifactType === 'skills' && scope === 'project')
       ? path.join(process.cwd(), '.claude', 'skills')
@@ -273,7 +318,7 @@ async function setup(args, flags = {}) {
         result = await installHooks(sourcesForType, installTarget, flags);
         break;
       case 'section-concat':
-        result = await installClaudeMd(sourcesForType, installTarget, flags);
+        result = await installSectionDocument(artifactType, sourcesForType, installTarget, flags);
         break;
       case 'deep-merge':
         result = await installSettings(sourcesForType, installTarget, flags);
@@ -293,6 +338,10 @@ async function setup(args, flags = {}) {
     }
   }
 
+  if (!flags.dryRun && scope === 'user') {
+    await writeInstallMetadata(root);
+  }
+
   console.log('\nDone.');
 }
 

package/src/cli/source.js

@@ -20,6 +20,26 @@ async function copyDirRecursive(src, dest) {
   }
 }
 
+function parseMappingFlag(mappingFlag) {
+  if (!mappingFlag) return {};
+
+  const entries = mappingFlag
+    .split(',')
+    .map(part => part.trim())
+    .filter(Boolean);
+
+  const mapping = {};
+  for (const entry of entries) {
+    const [artifactType, ...rest] = entry.split('=');
+    const target = rest.join('=').trim();
+    if (!artifactType || !target) {
+      throw new Error(`Invalid mapping entry "${entry}". Use artifact=path.`);
+    }
+    mapping[artifactType.trim()] = target;
+  }
+  return mapping;
+}
+
 async function syncRemoteSource(sourceName, sourceConfig, root) {
   console.log(`  Syncing ${sourceName} from ${sourceConfig.remote} (${sourceConfig.ref})...`);
 
@@ -85,6 +105,15 @@ async function source(args, flags = {}) {
         console.log(`${marker} ${name} (priority ${src.priority})`);
         console.log(`  ${location}`);
         console.log(`  artifacts: ${(src.artifacts || []).join(', ')}`);
+        if (src.role) {
+          console.log(`  role: ${src.role}`);
+        }
+        if (src.mapping && Object.keys(src.mapping).length > 0) {
+          const mapping = Object.entries(src.mapping)
+            .map(([artifact, target]) => `${artifact}=${target}`)
+            .join(', ');
+          console.log(`  mapping: ${mapping}`);
+        }
         console.log('');
       }
       break;
@@ -94,12 +123,14 @@ async function source(args, flags = {}) {
       const name = args[1];
       const remote = args[2];
       if (!name || !remote) {
-        throw new Error('Usage: omc-manage source add <name> <remote-url> [--ref main] [--priority N] [--artifacts skills,agents]');
+        throw new Error('Usage: omc-manage source add <name> <remote-url> [--ref main] [--priority N] [--artifacts skills,agents,guidelines] [--mapping guidelines=CLAUDE.md] [--role guidelines]');
       }
       await addSource(name, remote, {
         ref: flags.ref,
         priority: flags.priority,
         artifacts: flags.artifacts,
+        mapping: parseMappingFlag(flags.mapping),
+        role: flags.role,
       });
       console.log(`Source "${name}" added.`);
       console.log(`Run "omc-manage source sync ${name}" to fetch artifacts.`);
@@ -167,6 +198,9 @@ async function source(args, flags = {}) {
 
       for (const [name, src] of Object.entries(config.sources)) {
         console.log(`[${name}] (priority ${src.priority})`);
+        if (src.role) {
+          console.log(`  role: ${src.role}`);
+        }
         const artifacts = src.artifacts || [];
         for (const type of artifacts) {
           const dir = getSourceArtifactDir(name, type, root);

package/src/config/artifact-types.js

@@ -1,6 +1,8 @@
 const path = require('path');
 const os = require('os');
 
+const CLAUDE_MD_TARGET = path.join(os.homedir(), '.claude', 'CLAUDE.md');
+
 const ARTIFACT_TYPES = {
   skills: {
     label: 'Skills',
@@ -35,9 +37,17 @@ const ARTIFACT_TYPES = {
     metadataFile: null,
     mergeStrategy: 'name-based',
   },
+  guidelines: {
+    label: 'Guidelines',
+    installTarget: CLAUDE_MD_TARGET,
+    sourceSubdir: 'guidelines',
+    format: 'single-file',
+    metadataFile: null,
+    mergeStrategy: 'section-concat',
+  },
   'claude-md': {
-    label: 'CLAUDE.md',
-    installTarget: path.join(os.homedir(), '.claude', 'CLAUDE.md'),
+    label: 'CLAUDE.md (legacy)',
+    installTarget: CLAUDE_MD_TARGET,
     sourceSubdir: 'claude-md',
     format: 'single-file',
     metadataFile: null,

package/src/config/paths.js

@@ -34,6 +34,9 @@ function isDistributionMode() {
 function getSourceArtifactDir(sourceName, artifactType, root) {
   root = root || getProjectRoot();
 
+  const legacyArtifactType = artifactType === 'guidelines' ? 'claude-md' : null;
+  const modernArtifactType = artifactType === 'claude-md' ? 'guidelines' : null;
+
   if (isDistributionMode()) {
     if (sourceName === 'local') {
       // Check user-customized local first, then fall back to bundled .local/
@@ -41,21 +44,109 @@ function getSourceArtifactDir(sourceName, artifactType, root) {
       if (fs.existsSync(userLocal)) {
         return userLocal;
       }
-      return path.join(root, '.local', artifactType);
+      if (legacyArtifactType) {
+        const userLegacy = path.join(USER_DATA_DIR, 'local', legacyArtifactType);
+        if (fs.existsSync(userLegacy)) {
+          return userLegacy;
+        }
+      }
+      if (modernArtifactType) {
+        const userModern = path.join(USER_DATA_DIR, 'local', modernArtifactType);
+        if (fs.existsSync(userModern)) {
+          return userModern;
+        }
+      }
+      const bundledLocal = path.join(root, '.local', artifactType);
+      if (fs.existsSync(bundledLocal)) {
+        return bundledLocal;
+      }
+      if (legacyArtifactType) {
+        const bundledLegacy = path.join(root, '.local', legacyArtifactType);
+        if (fs.existsSync(bundledLegacy)) {
+          return bundledLegacy;
+        }
+      }
+      if (modernArtifactType) {
+        const bundledModern = path.join(root, '.local', modernArtifactType);
+        if (fs.existsSync(bundledModern)) {
+          return bundledModern;
+        }
+      }
+      return bundledLocal;
     }
     // Check user-synced first, then fall back to bundled
     const synced = path.join(USER_DATA_DIR, 'upstream', sourceName, artifactType);
     if (fs.existsSync(synced)) {
       return synced;
     }
-    return path.join(root, 'bundled', 'upstream', sourceName, artifactType);
+    if (legacyArtifactType) {
+      const syncedLegacy = path.join(USER_DATA_DIR, 'upstream', sourceName, legacyArtifactType);
+      if (fs.existsSync(syncedLegacy)) {
+        return syncedLegacy;
+      }
+    }
+    if (modernArtifactType) {
+      const syncedModern = path.join(USER_DATA_DIR, 'upstream', sourceName, modernArtifactType);
+      if (fs.existsSync(syncedModern)) {
+        return syncedModern;
+      }
+    }
+    const bundled = path.join(root, 'bundled', 'upstream', sourceName, artifactType);
+    if (fs.existsSync(bundled)) {
+      return bundled;
+    }
+    if (legacyArtifactType) {
+      const bundledLegacy = path.join(root, 'bundled', 'upstream', sourceName, legacyArtifactType);
+      if (fs.existsSync(bundledLegacy)) {
+        return bundledLegacy;
+      }
+    }
+    if (modernArtifactType) {
+      const bundledModern = path.join(root, 'bundled', 'upstream', sourceName, modernArtifactType);
+      if (fs.existsSync(bundledModern)) {
+        return bundledModern;
+      }
+    }
+    return bundled;
   }
 
   // Dev mode
   if (sourceName === 'local') {
-    return path.join(root, '.local', artifactType);
+    const localDir = path.join(root, '.local', artifactType);
+    if (fs.existsSync(localDir)) {
+      return localDir;
+    }
+    if (legacyArtifactType) {
+      const legacyDir = path.join(root, '.local', legacyArtifactType);
+      if (fs.existsSync(legacyDir)) {
+        return legacyDir;
+      }
+    }
+    if (modernArtifactType) {
+      const modernDir = path.join(root, '.local', modernArtifactType);
+      if (fs.existsSync(modernDir)) {
+        return modernDir;
+      }
+    }
+    return localDir;
   }
-  return path.join(root, '.upstream', sourceName, artifactType);
+  const upstreamDir = path.join(root, '.upstream', sourceName, artifactType);
+  if (fs.existsSync(upstreamDir)) {
+    return upstreamDir;
+  }
+  if (legacyArtifactType) {
+    const legacyDir = path.join(root, '.upstream', sourceName, legacyArtifactType);
+    if (fs.existsSync(legacyDir)) {
+      return legacyDir;
+    }
+  }
+  if (modernArtifactType) {
+    const modernDir = path.join(root, '.upstream', sourceName, modernArtifactType);
+    if (fs.existsSync(modernDir)) {
+      return modernDir;
+    }
+  }
+  return upstreamDir;
 }
 
 /**

package/src/config/sources.js

@@ -13,7 +13,7 @@ function getDefaultConfig() {
       local: {
         path: '.local',
         priority: 1,
-        artifacts: ['skills', 'agents', 'hooks', 'commands', 'claude-md', 'settings', 'hud'],
+        artifacts: ['skills', 'agents', 'hooks', 'commands', 'guidelines', 'settings', 'hud'],
       },
       'oh-my-claudecode': {
         remote: 'https://github.com/Yeachan-Heo/oh-my-claudecode.git',
@@ -56,14 +56,36 @@ function getDefaultConfig() {
   };
 }
 
+function dedupeArtifacts(artifacts) {
+  return [...new Set((artifacts || []).filter(Boolean))];
+}
+
+function normalizeConfig(config) {
+  const normalized = config || getDefaultConfig();
+  normalized.sources = normalized.sources || {};
+
+  for (const [name, source] of Object.entries(normalized.sources)) {
+    source.artifacts = dedupeArtifacts(source.artifacts);
+
+    // Migrate local prompt guidance from legacy claude-md to guidelines.
+    if (name === 'local' && source.artifacts.includes('claude-md') && !source.artifacts.includes('guidelines')) {
+      source.artifacts = source.artifacts.map((artifact) => (
+        artifact === 'claude-md' ? 'guidelines' : artifact
+      ));
+    }
+  }
+
+  return normalized;
+}
+
 function readConfig() {
   if (!fs.existsSync(CONFIG_PATH)) {
-    return getDefaultConfig();
+    return normalizeConfig(getDefaultConfig());
   }
   try {
-    return JSON.parse(fs.readFileSync(CONFIG_PATH, 'utf8'));
+    return normalizeConfig(JSON.parse(fs.readFileSync(CONFIG_PATH, 'utf8')));
   } catch {
-    return getDefaultConfig();
+    return normalizeConfig(getDefaultConfig());
   }
 }
 
@@ -71,7 +93,7 @@ async function writeConfig(config) {
   if (!fs.existsSync(CONFIG_DIR)) {
     await fsp.mkdir(CONFIG_DIR, { recursive: true });
   }
-  await fsp.writeFile(CONFIG_PATH, JSON.stringify(config, null, 2) + '\n', 'utf8');
+  await fsp.writeFile(CONFIG_PATH, JSON.stringify(normalizeConfig(config), null, 2) + '\n', 'utf8');
 }
 
 function getActiveSource() {
@@ -112,6 +134,7 @@ async function addSource(name, remote, options = {}) {
     priority: options.priority || Object.keys(config.sources).length + 1,
     artifacts: options.artifacts || ['skills'],
     mapping: options.mapping || {},
+    role: options.role,
   };
   await writeConfig(config);
 }
@@ -136,6 +159,7 @@ module.exports = {
   recordSync,
   addSource,
   removeSource,
+  normalizeConfig,
   CONFIG_DIR,
   CONFIG_PATH,
 };