fix(installer): harden locale docs install

scripts/ci/validate-install-manifests.js

@@ -21,6 +21,7 @@ const COMPONENT_FAMILY_PREFIXES = {
   language: 'lang:',
   framework: 'framework:',
   capability: 'capability:',
+  locale: 'locale:',
 };
 
 function readJson(filePath, label) {
@@ -163,9 +164,12 @@ function validateInstallManifests() {
 
   if (profiles.full) {
     const fullModules = new Set(profiles.full.modules);
-    for (const moduleId of moduleIds) {
-      if (!fullModules.has(moduleId)) {
-        console.error(`ERROR: full profile is missing module ${moduleId}`);
+    for (const module of modules) {
+      if (module.kind === 'docs' && module.defaultInstall === false) {
+        continue;
+      }
+      if (!fullModules.has(module.id)) {
+        console.error(`ERROR: full profile is missing module ${module.id}`);
         hasErrors = true;
       }
     }

scripts/lib/install-executor.js

@@ -555,6 +555,12 @@ function createLegacyCompatInstallPlan(options = {}) {
   const sourceRoot = options.sourceRoot || getSourceRoot();
   const projectRoot = options.projectRoot || process.cwd();
   const target = options.target || 'claude';
+  const includeComponentIds = Array.isArray(options.includeComponentIds)
+    ? [...options.includeComponentIds]
+    : [];
+  const excludeComponentIds = Array.isArray(options.excludeComponentIds)
+    ? [...options.excludeComponentIds]
+    : [];
 
   validateLegacyTarget(target);
 
@@ -571,14 +577,14 @@ function createLegacyCompatInstallPlan(options = {}) {
     target,
     profileId: null,
     moduleIds: selection.moduleIds,
-    includeComponentIds: [],
-    excludeComponentIds: [],
+    includeComponentIds,
+    excludeComponentIds,
     legacyLanguages: selection.legacyLanguages,
     legacyMode: true,
     requestProfileId: null,
     requestModuleIds: [],
-    requestIncludeComponentIds: [],
-    requestExcludeComponentIds: [],
+    requestIncludeComponentIds: includeComponentIds,
+    requestExcludeComponentIds: excludeComponentIds,
     mode: 'legacy-compat',
   });
 }

scripts/lib/install-manifests.js

@@ -18,17 +18,17 @@ const SUPPORTED_LOCALES = Object.freeze(['ja', 'zh-CN', 'ko-KR', 'pt-BR', 'ru',
 const LOCALE_ALIAS_TO_COMPONENT_ID = Object.freeze({
   'ja': 'locale:ja',
   'ja-JP': 'locale:ja',
-  'zh-CN': 'locale:zh-CN',
-  'zh': 'locale:zh-CN',
-  'ko-KR': 'locale:ko-KR',
-  'ko': 'locale:ko-KR',
-  'pt-BR': 'locale:pt-BR',
-  'pt': 'locale:pt-BR',
+  'zh-CN': 'locale:zh-cn',
+  'zh': 'locale:zh-cn',
+  'ko-KR': 'locale:ko-kr',
+  'ko': 'locale:ko-kr',
+  'pt-BR': 'locale:pt-br',
+  'pt': 'locale:pt-br',
   'ru': 'locale:ru',
   'tr': 'locale:tr',
-  'vi-VN': 'locale:vi-VN',
-  'vi': 'locale:vi-VN',
-  'zh-TW': 'locale:zh-TW',
+  'vi-VN': 'locale:vi-vn',
+  'vi': 'locale:vi-vn',
+  'zh-TW': 'locale:zh-tw',
 });
 
 function listSupportedLocales() {

scripts/lib/install/request.js

@@ -62,7 +62,11 @@ function parseInstallArgs(argv) {
       }
       index += 1;
     } else if (arg === '--locale') {
-      parsed.locale = args[index + 1] || null;
+      const locale = args[index + 1] || '';
+      if (!locale || locale.startsWith('--')) {
+        throw new Error('Missing value for --locale');
+      }
+      parsed.locale = locale;
       index += 1;
     } else if (arg === '--dry-run') {
       parsed.dryRun = true;
@@ -85,6 +89,7 @@ function normalizeInstallRequest(options = {}) {
     ? options.config
     : null;
   const profileId = options.profileId || config?.profileId || null;
+  const target = options.target || config?.target || 'claude';
   const moduleIds = validateInstallModuleIds(
     dedupeStrings([...(config?.moduleIds || []), ...(options.moduleIds || [])])
   );
@@ -95,9 +100,15 @@ function normalizeInstallRequest(options = {}) {
       `Unsupported locale: "${locale}". Supported locales: ${listSupportedLocales().join(', ')}`
     );
   }
-  const includeComponentIds = dedupeStrings([
+  if (locale && target !== 'claude') {
+    throw new Error('--locale can only be used with --target claude');
+  }
+  const requestedIncludeComponentIds = dedupeStrings([
     ...(config?.includeComponentIds || []),
     ...(options.includeComponentIds || []),
+  ]);
+  const includeComponentIds = dedupeStrings([
+    ...requestedIncludeComponentIds,
     ...(localeComponentId ? [localeComponentId] : []),
   ]);
   const excludeComponentIds = dedupeStrings([
@@ -108,13 +119,16 @@ function normalizeInstallRequest(options = {}) {
     ...(Array.isArray(options.legacyLanguages) ? options.legacyLanguages : []),
     ...(Array.isArray(options.languages) ? options.languages : []),
   ]).map(language => language.toLowerCase()));
-  const target = options.target || config?.target || 'claude';
   const hasManifestBaseSelection = Boolean(profileId) || moduleIds.length > 0 || includeComponentIds.length > 0;
+  const hasNonLocaleManifestSelection = Boolean(profileId)
+    || moduleIds.length > 0
+    || requestedIncludeComponentIds.length > 0
+    || excludeComponentIds.length > 0;
   const usingManifestMode = hasManifestBaseSelection || excludeComponentIds.length > 0;
 
-  if (usingManifestMode && legacyLanguages.length > 0) {
+  if (hasNonLocaleManifestSelection && legacyLanguages.length > 0) {
     throw new Error(
-      'Legacy language arguments cannot be combined with --profile, --modules, --with, --without, --locale, or manifest config selections'
+      'Legacy language arguments cannot be combined with --profile, --modules, --with, --without, or manifest config selections'
     );
   }
 
@@ -123,7 +137,9 @@ function normalizeInstallRequest(options = {}) {
   }
 
   return {
-    mode: usingManifestMode ? 'manifest' : 'legacy-compat',
+    mode: legacyLanguages.length > 0
+      ? 'legacy-compat'
+      : (usingManifestMode ? 'manifest' : 'legacy-compat'),
     target,
     profileId,
     moduleIds,

scripts/lib/install/runtime.js

@@ -28,6 +28,8 @@ function createInstallPlanFromRequest(request, options = {}) {
     return createLegacyCompatInstallPlan({
       target: request.target,
       legacyLanguages: request.legacyLanguages,
+      includeComponentIds: request.includeComponentIds,
+      excludeComponentIds: request.excludeComponentIds,
       projectRoot: options.projectRoot,
       homeDir: options.homeDir,
       claudeRulesDir: options.claudeRulesDir,