ocx 2.0.0 → 2.0.1

package/dist/index.js

@@ -1,4 +1,4 @@
-#!/usr/bin/env bun
+#!/usr/bin/env -S bun --no-env-file
 // @bun
 var __create = Object.create;
 var __getProtoOf = Object.getPrototypeOf;
@@ -6098,7 +6098,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "ocx",
-    version: "2.0.0",
+    version: "2.0.1",
     description: "OCX CLI - ShadCN-style registry for OpenCode extensions. Install agents, plugins, skills, and MCP servers.",
     author: "kdcokenny",
     license: "MIT",
@@ -6178,7 +6178,7 @@ var init_constants = __esm(() => {
 });
 
 // src/utils/errors.ts
-var EXIT_CODES, OCXError, NotFoundError, NetworkError, ConfigError, ValidationError, ConflictError, IntegrityError, SelfUpdateError, RegistryCompatibilityError, ProfileNotFoundError, ProfileExistsError, RegistryExistsError, InvalidProfileNameError, ProfilesNotInitializedError, LocalProfileUnsupportedError;
+var EXIT_CODES, OCXError, NotFoundError, NetworkError, ConfigError, ValidationError, ValidationFailedError, ConflictError, IntegrityError, SelfUpdateError, RegistryCompatibilityError, ProfileNotFoundError, ProfileExistsError, RegistryExistsError, InvalidProfileNameError, ProfilesNotInitializedError, LocalProfileUnsupportedError;
 var init_errors2 = __esm(() => {
   EXIT_CODES = {
     SUCCESS: 0,
@@ -6209,12 +6209,20 @@ var init_errors2 = __esm(() => {
     url;
     status;
     statusText;
+    phase;
+    qualifiedName;
+    registryContext;
+    registryName;
     constructor(message, options) {
       super(message, "NETWORK_ERROR", EXIT_CODES.NETWORK);
       this.name = "NetworkError";
       this.url = options?.url;
       this.status = options?.status;
       this.statusText = options?.statusText;
+      this.phase = options?.phase;
+      this.qualifiedName = options?.qualifiedName;
+      this.registryContext = options?.registryContext;
+      this.registryName = options?.registryName;
     }
   };
   ConfigError = class ConfigError extends OCXError {
@@ -6229,6 +6237,14 @@ var init_errors2 = __esm(() => {
       this.name = "ValidationError";
     }
   };
+  ValidationFailedError = class ValidationFailedError extends OCXError {
+    details;
+    constructor(details) {
+      super("Registry validation failed", "VALIDATION_FAILED", EXIT_CODES.CONFIG);
+      this.details = details;
+      this.name = "ValidationFailedError";
+    }
+  };
   ConflictError = class ConflictError extends OCXError {
     constructor(message) {
       super(message, "CONFLICT", EXIT_CODES.CONFLICT);
@@ -7060,24 +7076,29 @@ function adaptLegacyRegistryIndex(data, url) {
     components: adaptedComponents
   };
 }
-async function fetchWithCache(url, parse3) {
-  const cached = cache.get(url);
+async function fetchWithCache(cacheKey, parse3, options = {}) {
+  const cached = cache.get(cacheKey);
   if (cached) {
     return cached;
   }
+  const requestUrl = options.requestUrl ?? cacheKey;
   const promise = (async () => {
+    const networkErrorContext = {
+      url: requestUrl,
+      phase: options.phase
+    };
     let response;
     try {
-      response = await fetch(url);
+      response = await fetch(requestUrl);
     } catch (error) {
-      throw new NetworkError(`Network request failed for ${url}: ${error instanceof Error ? error.message : String(error)}`, { url });
+      throw new NetworkError(`Network request failed for ${requestUrl}: ${error instanceof Error ? error.message : String(error)}`, networkErrorContext);
     }
     if (!response.ok) {
       if (response.status === 404) {
-        throw new NotFoundError(`Not found: ${url}`);
+        throw new NotFoundError(`Not found: ${requestUrl}`);
       }
-      throw new NetworkError(`Failed to fetch ${url}: ${response.status} ${response.statusText}`, {
-        url,
+      throw new NetworkError(`Failed to fetch ${requestUrl}: ${response.status} ${response.statusText}`, {
+        ...networkErrorContext,
         status: response.status,
         statusText: response.statusText
       });
@@ -7086,12 +7107,12 @@ async function fetchWithCache(url, parse3) {
     try {
       data = await response.json();
     } catch (error) {
-      throw new NetworkError(`Invalid JSON response from ${url}: ${error instanceof Error ? error.message : String(error)}`, { url });
+      throw new NetworkError(`Invalid JSON response from ${requestUrl}: ${error instanceof Error ? error.message : String(error)}`, networkErrorContext);
     }
     return await parse3(data);
   })();
-  cache.set(url, promise);
-  promise.catch(() => cache.delete(url));
+  cache.set(cacheKey, promise);
+  promise.catch(() => cache.delete(cacheKey));
   return promise;
 }
 function classifyRegistryIndexIssue(data) {
@@ -7156,7 +7177,7 @@ async function fetchRegistryIndex(baseUrl) {
     }
     registrySchemaModeCache.set(normalizedBaseUrl, schemaMode);
     return result.data;
-  });
+  }, { phase: "registry-index-fetch" });
 }
 async function fetchComponent(baseUrl, name) {
   const result = await fetchComponentVersion(baseUrl, name);
@@ -7202,18 +7223,27 @@ async function fetchComponentVersion(baseUrl, name, version) {
       throw new ValidationError(`Invalid component manifest for "${name}@${resolvedVersion}": ${manifestResult.error.message}`);
     }
     return { manifest: manifestResult.data, version: resolvedVersion };
-  });
+  }, { phase: "packument-fetch", requestUrl: url });
 }
 async function fetchFileContent(baseUrl, componentName, filePath) {
   const url = `${normalizeRegistryUrl(baseUrl)}/components/${componentName}/${filePath}`;
+  const networkErrorContext = {
+    url,
+    phase: "file-content-fetch",
+    qualifiedName: componentName
+  };
   let response;
   try {
     response = await fetch(url);
   } catch (error) {
-    throw new NetworkError(`Network request failed for ${url}: ${error instanceof Error ? error.message : String(error)}`, { url });
+    throw new NetworkError(`Network request failed for ${url}: ${error instanceof Error ? error.message : String(error)}`, networkErrorContext);
   }
   if (!response.ok) {
-    throw new NetworkError(`Failed to fetch file ${filePath} for ${componentName} from ${url}: ${response.status} ${response.statusText}`, { url, status: response.status, statusText: response.statusText });
+    throw new NetworkError(`Failed to fetch file ${filePath} for ${componentName} from ${url}: ${response.status} ${response.statusText}`, {
+      ...networkErrorContext,
+      status: response.status,
+      statusText: response.statusText
+    });
   }
   return response.text();
 }
@@ -11376,6 +11406,9 @@ class GlobalConfigProvider {
       throw new ConfigError("Global config not found. Run 'ocx init --global' first.");
     }
     const config = await readOcxConfig(basePath);
+    if (!config) {
+      throw new ConfigError("Global config not found. Run 'ocx init --global' first.");
+    }
     return new GlobalConfigProvider(basePath, config);
   }
   getRegistries() {
@@ -13300,6 +13333,14 @@ function formatErrorAsJson(error) {
       details.status = error.status;
     if (error.statusText)
       details.statusText = error.statusText;
+    if (error.phase)
+      details.phase = error.phase;
+    if (error.qualifiedName)
+      details.qualifiedName = error.qualifiedName;
+    if (error.registryContext)
+      details.registryContext = error.registryContext;
+    if (error.registryName)
+      details.registryName = error.registryName;
     return {
       success: false,
       error: {
@@ -13403,6 +13444,20 @@ function formatErrorAsJson(error) {
       }
     };
   }
+  if (error instanceof ValidationFailedError) {
+    return {
+      success: false,
+      error: {
+        code: error.code,
+        message: error.message,
+        details: error.details
+      },
+      exitCode: error.exitCode,
+      meta: {
+        timestamp: new Date().toISOString()
+      }
+    };
+  }
   if (error instanceof OCXError) {
     return {
       success: false,
@@ -15942,11 +15997,343 @@ async function updateOpencodePackageDeps(cwd, npmDeps, npmDevDeps, options2 = {}
 
 // src/commands/build.ts
 import { relative as relative5, resolve as resolve6 } from "path";
+
+// src/lib/validators.ts
+import { join as join9, posix } from "path";
+init_registry();
+function formatJsoncParseError3(parseErrors) {
+  if (parseErrors.length === 0) {
+    return "Unknown parse error";
+  }
+  const firstError = parseErrors[0];
+  if (!firstError) {
+    return "Unknown parse error";
+  }
+  return `${printParseErrorCode(firstError.error)} at offset ${firstError.offset}`;
+}
+async function loadRegistrySource(sourcePath) {
+  const jsoncFile = Bun.file(`${sourcePath}/registry.jsonc`);
+  const jsonFile = Bun.file(`${sourcePath}/registry.json`);
+  const jsoncExists = await jsoncFile.exists();
+  const jsonExists = await jsonFile.exists();
+  if (!jsoncExists && !jsonExists) {
+    return {
+      success: false,
+      error: "No registry.jsonc or registry.json found in source directory",
+      errorKind: "not_found"
+    };
+  }
+  const registryFile = jsoncExists ? jsoncFile : jsonFile;
+  const fileName = jsoncExists ? "registry.jsonc" : "registry.json";
+  const content2 = await registryFile.text();
+  const parseErrors = [];
+  const data = parse2(content2, parseErrors, { allowTrailingComma: true });
+  if (parseErrors.length > 0) {
+    const errorDetail = formatJsoncParseError3(parseErrors);
+    return {
+      success: false,
+      error: `Invalid JSONC in ${fileName}: ${errorDetail}`,
+      errorKind: "parse_error"
+    };
+  }
+  return {
+    success: true,
+    data
+  };
+}
+function validateRegistrySchema(registryData, sourcePath) {
+  const schemaIssue = classifyRegistrySchemaIssue(registryData);
+  if (schemaIssue) {
+    return {
+      valid: false,
+      errors: [`Schema compatibility issue: ${schemaIssue.issue} - ${schemaIssue.remediation}`]
+    };
+  }
+  return validateRegistrySource(registryData, sourcePath);
+}
+function validateRegistrySource(registryData, _sourcePath) {
+  const parseResult = registrySchema.safeParse(registryData);
+  if (!parseResult.success) {
+    const errors3 = parseResult.error.errors.map((e3) => `${e3.path.join(".")}: ${e3.message}`);
+    return {
+      valid: false,
+      errors: errors3
+    };
+  }
+  return {
+    valid: true,
+    errors: [],
+    data: parseResult.data
+  };
+}
+async function validateSourceFiles(registry, sourcePath) {
+  const errors3 = [];
+  for (const component of registry.components) {
+    for (const rawFile of component.files) {
+      const file = normalizeFile(rawFile, component.type);
+      const sourceFilePath = join9(sourcePath, "files", file.path);
+      if (!await Bun.file(sourceFilePath).exists()) {
+        errors3.push(`${component.name}: Source file not found at ${file.path}`);
+      }
+    }
+  }
+  return {
+    valid: errors3.length === 0,
+    errors: errors3
+  };
+}
+function validateCircularDependencies(registry) {
+  const errors3 = [];
+  const componentMap = new Map(registry.components.map((c) => [c.name, c]));
+  function detectCycle(componentName, visiting, visited, path7) {
+    if (visiting.has(componentName)) {
+      return [...path7, componentName].join(" -> ");
+    }
+    if (visited.has(componentName)) {
+      return null;
+    }
+    const component = componentMap.get(componentName);
+    if (!component) {
+      return null;
+    }
+    visiting.add(componentName);
+    path7.push(componentName);
+    for (const dep of component.dependencies) {
+      if (dep.includes("/")) {
+        continue;
+      }
+      const cycle = detectCycle(dep, visiting, visited, path7);
+      if (cycle) {
+        return cycle;
+      }
+    }
+    visiting.delete(componentName);
+    visited.add(componentName);
+    path7.pop();
+    return null;
+  }
+  const globalVisited = new Set;
+  for (const component of registry.components) {
+    if (globalVisited.has(component.name)) {
+      continue;
+    }
+    const cycle = detectCycle(component.name, new Set, globalVisited, []);
+    if (cycle) {
+      errors3.push(`Circular dependency detected: ${cycle}`);
+      break;
+    }
+  }
+  return {
+    valid: errors3.length === 0,
+    errors: errors3
+  };
+}
+function validateDuplicateTargets(registry) {
+  const errors3 = [];
+  const targetMap = new Map;
+  const canonicalizeTargetForComparison = (target) => {
+    const normalizedUnicode = target.normalize("NFC");
+    const unifiedSeparators = normalizedUnicode.replace(/\\/g, "/");
+    const normalizedTarget = posix.normalize(unifiedSeparators);
+    return normalizedTarget.replace(/^\.\//, "");
+  };
+  for (const component of registry.components) {
+    for (const rawFile of component.files) {
+      const file = normalizeFile(rawFile, component.type);
+      const canonicalTarget = canonicalizeTargetForComparison(file.target);
+      const existing = targetMap.get(canonicalTarget);
+      if (existing) {
+        errors3.push(`Duplicate target "${canonicalTarget}" in components "${existing.componentName}" and "${component.name}"`);
+      } else {
+        targetMap.set(canonicalTarget, {
+          componentName: component.name
+        });
+      }
+    }
+  }
+  return {
+    valid: errors3.length === 0,
+    errors: errors3
+  };
+}
+async function* validateRegistryWithOptions(registry, sourcePath, options2 = {}) {
+  const filesResult = await validateSourceFiles(registry, sourcePath);
+  for (const error of filesResult.errors) {
+    yield error;
+  }
+  const circularResult = validateCircularDependencies(registry);
+  for (const error of circularResult.errors) {
+    yield error;
+  }
+  if (!options2.skipDuplicateTargets) {
+    const duplicateTargetsResult = validateDuplicateTargets(registry);
+    for (const error of duplicateTargetsResult.errors) {
+      yield error;
+    }
+  }
+}
+
+// src/lib/validation-runner.ts
+async function runCompleteValidation(sourcePath, options2 = {}) {
+  const loadResult = await loadRegistrySource(sourcePath);
+  if (!loadResult.success) {
+    return {
+      success: false,
+      errors: [loadResult.error || "Failed to load registry"],
+      failureType: "load",
+      loadErrorKind: loadResult.errorKind
+    };
+  }
+  const schemaResult = validateRegistrySchema(loadResult.data, sourcePath);
+  if (!schemaResult.valid) {
+    return {
+      success: false,
+      errors: schemaResult.errors,
+      failureType: "schema"
+    };
+  }
+  const registry = schemaResult.data;
+  if (!registry) {
+    throw new Error("Registry validation succeeded but returned no parsed data");
+  }
+  const validationErrors = [];
+  for await (const error of validateRegistryWithOptions(registry, sourcePath, options2)) {
+    validationErrors.push(error);
+  }
+  if (validationErrors.length > 0) {
+    return {
+      success: false,
+      errors: validationErrors,
+      failureType: "rules"
+    };
+  }
+  return {
+    success: true,
+    errors: [],
+    registry
+  };
+}
+
+// src/commands/build.ts
+init_errors2();
+
+// src/utils/validation-errors.ts
+function categorizeValidationErrors(errors3) {
+  return {
+    file: errors3.filter((e3) => e3.includes("Source file not found")),
+    circular: errors3.filter((e3) => e3.includes("Circular dependency")),
+    duplicate: errors3.filter((e3) => e3.includes("Duplicate target"))
+  };
+}
+function summarizeValidationErrors(errors3, options2 = {}) {
+  const categorized = categorizeValidationErrors(errors3);
+  const schemaErrors = options2.schemaErrors ?? 0;
+  const totalErrors = errors3.length;
+  const otherErrors = Math.max(0, totalErrors - schemaErrors - categorized.file.length - categorized.circular.length - categorized.duplicate.length);
+  return {
+    valid: totalErrors === 0,
+    totalErrors,
+    schemaErrors,
+    sourceFileErrors: categorized.file.length,
+    circularDependencyErrors: categorized.circular.length,
+    duplicateTargetErrors: categorized.duplicate.length,
+    otherErrors
+  };
+}
+
+// src/commands/build.ts
+function createLoadValidationError(message, errorKind) {
+  if (errorKind === "not_found") {
+    return new NotFoundError(message);
+  }
+  if (errorKind === "parse_error") {
+    return new OCXError(message, "CONFIG_ERROR", EXIT_CODES.CONFIG);
+  }
+  return new OCXError(message, "CONFIG_ERROR", EXIT_CODES.CONFIG);
+}
+function createValidationFailureError(errors3, failureType) {
+  const summary = summarizeValidationErrors(errors3, {
+    schemaErrors: failureType === "schema" ? errors3.length : 0
+  });
+  const details = {
+    valid: false,
+    errors: errors3,
+    summary: {
+      valid: false,
+      totalErrors: summary.totalErrors,
+      schemaErrors: summary.schemaErrors,
+      sourceFileErrors: summary.sourceFileErrors,
+      circularDependencyErrors: summary.circularDependencyErrors,
+      duplicateTargetErrors: summary.duplicateTargetErrors,
+      otherErrors: summary.otherErrors
+    }
+  };
+  return new ValidationFailedError(details);
+}
+function outputValidationFailures(errors3, failureType) {
+  if (failureType === "schema") {
+    logger.error("\u2717 Registry schema");
+    for (const error of errors3) {
+      console.log(kleur_default.red(`  ${error}`));
+    }
+    return;
+  }
+  const categorized = categorizeValidationErrors(errors3);
+  if (categorized.file.length > 0) {
+    logger.error("\u2717 Source files");
+    for (const error of categorized.file) {
+      console.log(kleur_default.red(`  ${error}`));
+    }
+  }
+  if (categorized.circular.length > 0) {
+    logger.error("\u2717 Circular dependencies");
+    for (const error of categorized.circular) {
+      console.log(kleur_default.red(`  ${error}`));
+    }
+  }
+  if (categorized.duplicate.length > 0) {
+    logger.error("\u2717 Duplicate targets");
+    for (const error of categorized.duplicate) {
+      console.log(kleur_default.red(`  ${error}`));
+    }
+  }
+}
 function registerBuildCommand(program2) {
-  program2.command("build").description("Build a registry from source (for registry authors)").argument("[path]", "Registry source directory", ".").option("--out <dir>", "Output directory", "./dist").option("--cwd <path>", "Working directory", process.cwd()).option("--json", "Output as JSON", false).option("-q, --quiet", "Suppress output", false).option("--dry-run", "Validate and show what would be built").action(async (path7, options2) => {
+  program2.command("build").description("Build a registry from source (for registry authors)").argument("[path]", "Registry source directory", ".").option("--out <dir>", "Output directory", "./dist").option("--cwd <path>", "Working directory", process.cwd()).option("--json", "Output as JSON", false).option("-q, --quiet", "Suppress output", false).option("--dry-run", "Validate and show what would be built").option("--show-validation", "Display validation results before building", false).action(async (path7, options2) => {
     try {
       const sourcePath = resolve6(options2.cwd, path7);
       const outPath = resolve6(options2.cwd, options2.out);
+      if (options2.showValidation) {
+        const shouldDisplayValidation = !options2.json && !options2.quiet;
+        if (shouldDisplayValidation) {
+          logger.info("Running validation checks...");
+        }
+        const validationResult = await runCompleteValidation(sourcePath, {
+          skipDuplicateTargets: false
+        });
+        if (!validationResult.success) {
+          const [firstError = "Registry validation failed"] = validationResult.errors;
+          if (validationResult.failureType === "load") {
+            throw createLoadValidationError(firstError, validationResult.loadErrorKind);
+          }
+          const failureType = validationResult.failureType === "schema" ? "schema" : "rules";
+          const validationError = createValidationFailureError(validationResult.errors, failureType);
+          if (options2.json) {
+            throw validationError;
+          }
+          if (!options2.quiet) {
+            outputValidationFailures(validationResult.errors, failureType);
+          }
+          process.exit(validationError.exitCode);
+        }
+        if (shouldDisplayValidation) {
+          logger.success("\u2713 Schema compatibility and structure");
+          logger.success("\u2713 Source files");
+          logger.success("\u2713 No circular dependencies");
+          logger.success("\u2713 No duplicate targets");
+          console.log("");
+        }
+      }
       const spinner2 = createSpinner({
         text: "Building registry...",
         quiet: options2.quiet || options2.json
@@ -15983,7 +16370,10 @@ function registerBuildCommand(program2) {
       }
     } catch (error) {
       if (error instanceof BuildRegistryError) {
-        if (!options2.json) {
+        if (options2.json) {
+          handleError(error, { json: true });
+        }
+        if (!options2.quiet) {
           logger.error(error.message);
           for (const err of error.errors) {
             console.log(kleur_default.red(`  ${err}`));
@@ -15999,7 +16389,7 @@ function registerBuildCommand(program2) {
 // src/commands/config/edit.ts
 import { existsSync as existsSync11 } from "fs";
 import { mkdir as mkdir6 } from "fs/promises";
-import { join as join9 } from "path";
+import { join as join10 } from "path";
 init_errors2();
 function registerConfigEditCommand(parent) {
   parent.command("edit").description("Open configuration file in editor").option("-g, --global", "Edit global ocx.jsonc").option("-p, --profile <name>", "Edit specific profile's config").action(async (options2) => {
@@ -16035,11 +16425,11 @@ Run 'ocx init --global' first.`);
   } else {
     const localConfigDir = findLocalConfigDir(process.cwd());
     if (localConfigDir) {
-      configPath = join9(localConfigDir, OCX_CONFIG_FILE);
+      configPath = join10(localConfigDir, OCX_CONFIG_FILE);
     } else {
-      const newConfigDir = join9(process.cwd(), LOCAL_CONFIG_DIR2);
+      const newConfigDir = join10(process.cwd(), LOCAL_CONFIG_DIR2);
       await mkdir6(newConfigDir, { recursive: true });
-      configPath = join9(newConfigDir, OCX_CONFIG_FILE);
+      configPath = join10(newConfigDir, OCX_CONFIG_FILE);
       if (!existsSync11(configPath)) {
         const defaultConfig = {
           $schema: "https://ocx.kdco.dev/schemas/ocx.json",
@@ -16171,7 +16561,7 @@ function registerConfigCommand(program2) {
 init_constants();
 import { existsSync as existsSync12 } from "fs";
 import { cp, mkdir as mkdir7, readdir as readdir2, readFile, rm as rm4, writeFile as writeFile2 } from "fs/promises";
-import { dirname as dirname4, join as join10 } from "path";
+import { dirname as dirname4, join as join11 } from "path";
 init_errors2();
 var TEMPLATE_REPO = "kdcokenny/ocx";
 var TEMPLATE_PATH = "examples/registry-starter";
@@ -16381,7 +16771,7 @@ async function copyDir(src, dest) {
 }
 function getReleaseTag() {
   if (false) {}
-  return `v${"2.0.0"}`;
+  return `v${"2.0.1"}`;
 }
 function getTemplateUrl(version) {
   const ref = version === "main" ? "heads/main" : `tags/${version}`;
@@ -16396,10 +16786,10 @@ async function fetchAndExtractTemplate(destDir, version, verbose) {
   if (!response.ok || !response.body) {
     throw new NetworkError(`Failed to fetch template from ${tarballUrl}: ${response.statusText}`);
   }
-  const tempDir = join10(destDir, ".ocx-temp");
+  const tempDir = join11(destDir, ".ocx-temp");
   await mkdir7(tempDir, { recursive: true });
   try {
-    const tarPath = join10(tempDir, "template.tar.gz");
+    const tarPath = join11(tempDir, "template.tar.gz");
     const arrayBuffer = await response.arrayBuffer();
     await writeFile2(tarPath, Buffer.from(arrayBuffer));
     const proc = Bun.spawn(["tar", "-xzf", tarPath, "-C", tempDir], {
@@ -16416,7 +16806,7 @@ async function fetchAndExtractTemplate(destDir, version, verbose) {
     if (!extractedDir) {
       throw new Error("Failed to find extracted template directory");
     }
-    const templateDir = join10(tempDir, extractedDir, TEMPLATE_PATH);
+    const templateDir = join11(tempDir, extractedDir, TEMPLATE_PATH);
     await copyDir(templateDir, destDir);
   } finally {
     await rm4(tempDir, { recursive: true, force: true });
@@ -16434,7 +16824,7 @@ async function replacePlaceholders(dir, values) {
     "AGENTS.md"
   ];
   for (const file of filesToProcess) {
-    const filePath = join10(dir, file);
+    const filePath = join11(dir, file);
     if (!existsSync12(filePath))
       continue;
     let content2 = await readFile(filePath).then((b) => b.toString());
@@ -16456,7 +16846,7 @@ async function replacePlaceholders(dir, values) {
 // src/commands/migrate/index.ts
 import { existsSync as existsSync13, readdirSync, readFileSync as readFileSync3, statSync as statSync4 } from "fs";
 import { rename as rename4, writeFile as writeFile3 } from "fs/promises";
-import { join as join11 } from "path";
+import { join as join12 } from "path";
 
 // src/commands/migrate/transform.ts
 init_errors2();
@@ -16630,12 +17020,12 @@ async function runGlobalMigrate(options2) {
 function discoverGlobalTargets(globalRoot) {
   const targets = [];
   targets.push({ label: "root", path: globalRoot });
-  const profilesDir = join11(globalRoot, "profiles");
+  const profilesDir = join12(globalRoot, "profiles");
   if (existsSync13(profilesDir) && statSync4(profilesDir).isDirectory()) {
     const entries = readdirSync(profilesDir, { withFileTypes: true });
     const profileNames = entries.filter((e3) => e3.isDirectory() && !e3.name.startsWith(".")).map((e3) => e3.name).sort();
     for (const name of profileNames) {
-      targets.push({ label: `profile:${name}`, path: join11(profilesDir, name) });
+      targets.push({ label: `profile:${name}`, path: join12(profilesDir, name) });
     }
   }
   return targets;
@@ -17156,53 +17546,661 @@ function formatTerminalName(cwd, profileName, gitInfo) {
   return `ocx[${profileName}]:${repoName}/${branch}`;
 }
 
-// src/commands/opencode.ts
-function dedupeLastWins(items) {
-  const seen = new Set;
-  const result = [];
-  for (let i = items.length - 1;i >= 0; i--) {
-    const item = items[i];
-    if (!seen.has(item)) {
-      seen.add(item);
-      result.unshift(item);
-    }
+// src/commands/opencode-overlay.ts
+import { randomUUID as randomUUID2 } from "crypto";
+import {
+  copyFile,
+  cp as cp2,
+  lstat as lstat2,
+  mkdir as mkdir8,
+  mkdtemp,
+  readdir as readdir3,
+  readFile as readFile2,
+  realpath,
+  rename as rename5,
+  rm as rm5,
+  unlink as unlink3
+} from "fs/promises";
+import { tmpdir } from "os";
+import { basename as basename3, dirname as dirname5, isAbsolute as isAbsolute7, join as join13, relative as relative6 } from "path";
+var {Glob: Glob4 } = globalThis.Bun;
+init_zod();
+init_errors2();
+init_path_security();
+var OPENCODE_OVERLAY_SOURCE_SCOPES = ["agent", "agents", "skill", "skills"];
+var OPENCODE_MERGED_DIR_PREFIX = "ocx-oc-merged-";
+var OVERLAY_TRANSACTION_MANIFEST_VERSION = 1;
+var OVERLAY_NATIVE_HELPER_REQUIRED_MESSAGE = "Full TOCTOU/symlink-swap hardening requires an fd-based native helper transaction.";
+function createOpencodeOcError(errorClass, detail) {
+  return new ConfigError(`ocx oc ${errorClass} error: ${detail}`);
+}
+function formatUnknownError(error) {
+  if (error instanceof Error) {
+    return error.message;
   }
-  return result;
+  return String(error);
 }
-function resolveOpenCodeBinary(opts) {
-  return opts.configBin ?? opts.envBin ?? "opencode";
+function formatJsoncParseError4(parseErrors) {
+  if (parseErrors.length === 0) {
+    return "Unknown parse error";
+  }
+  const firstError = parseErrors[0];
+  if (!firstError) {
+    return "Unknown parse error";
+  }
+  return `${printParseErrorCode(firstError.error)} at offset ${firstError.offset}`;
 }
-function buildOpenCodeEnv(opts) {
-  const hasProfile = Boolean(opts.profileName);
+function toPosixPath(pathValue) {
+  return pathValue.replaceAll("\\", "/");
+}
+function normalizeGlobPattern(pattern) {
+  return pattern.startsWith("./") ? pattern.slice(2) : pattern;
+}
+function isPathWithin(parentPath, childPath) {
+  const relativePath = relative6(parentPath, childPath);
+  if (relativePath.length === 0) {
+    return true;
+  }
+  return !relativePath.startsWith("..") && !isAbsolute7(relativePath);
+}
+function getOverlayEntryType(stats) {
+  if (stats.isFile()) {
+    return "file";
+  }
+  if (stats.isDirectory()) {
+    return "directory";
+  }
+  if (stats.isSymbolicLink()) {
+    return "symlink";
+  }
+  return "other";
+}
+function captureOverlaySnapshot(stats) {
   return {
-    ...opts.baseEnv,
-    ...hasProfile && { OPENCODE_DISABLE_PROJECT_CONFIG: "true" },
-    OPENCODE_CONFIG_DIR: hasProfile ? getProfileDir(opts.profileName) : getGlobalConfigPath(),
-    ...opts.configContent && { OPENCODE_CONFIG_CONTENT: opts.configContent },
-    ...opts.profileName && { OCX_PROFILE: opts.profileName }
+    entryType: getOverlayEntryType(stats),
+    device: String(stats.dev),
+    inode: String(stats.ino),
+    mode: String(stats.mode),
+    size: String(stats.size),
+    mtimeMs: String(stats.mtimeMs)
   };
 }
-function registerOpencodeCommand(program2) {
-  program2.command("oc").alias("opencode").description("Launch OpenCode with resolved configuration").option("-p, --profile <name>", "Use specific profile").option("--no-rename", "Disable terminal/tmux window renaming").allowUnknownOption().allowExcessArguments(true).action(async (options2, command) => {
+function overlaySnapshotIdentityMatches(expected, actual) {
+  return expected.entryType === actual.entryType && expected.device === actual.device && expected.inode === actual.inode && expected.mode === actual.mode;
+}
+function overlaySnapshotContentMatches(expected, actual) {
+  return expected.size === actual.size && expected.mtimeMs === actual.mtimeMs;
+}
+async function assertPathSnapshotUnchanged(options2) {
+  let currentStats;
+  try {
+    currentStats = await lstat2(options2.absolutePath);
+  } catch {
+    throw createOpencodeOcError("validate", `Overlay path changed during ${options2.phase}: ${options2.overlayRelativePath}. ${OVERLAY_NATIVE_HELPER_REQUIRED_MESSAGE}`);
+  }
+  if (options2.mustRemainDirectory && !currentStats.isDirectory()) {
+    throw createOpencodeOcError("validate", `Overlay path changed during ${options2.phase}: ${options2.overlayRelativePath}. ${OVERLAY_NATIVE_HELPER_REQUIRED_MESSAGE}`);
+  }
+  if (options2.mustRemainFile && !currentStats.isFile()) {
+    throw createOpencodeOcError("validate", `Overlay path changed during ${options2.phase}: ${options2.overlayRelativePath}. ${OVERLAY_NATIVE_HELPER_REQUIRED_MESSAGE}`);
+  }
+  const currentSnapshot = captureOverlaySnapshot(currentStats);
+  const identityMatches = overlaySnapshotIdentityMatches(options2.expectedSnapshot, currentSnapshot);
+  const shouldCompareContent = options2.compareContent ?? true;
+  const contentMatches = !shouldCompareContent ? true : overlaySnapshotContentMatches(options2.expectedSnapshot, currentSnapshot);
+  if (!identityMatches || !contentMatches) {
+    throw createOpencodeOcError("validate", `Overlay path changed during ${options2.phase}: ${options2.overlayRelativePath}. ${OVERLAY_NATIVE_HELPER_REQUIRED_MESSAGE}`);
+  }
+}
+async function assertSafeOverlayDestinationPath(mergedConfigDir, destinationPath, destinationRelativePath) {
+  const relativeDestinationPath = toPosixPath(relative6(mergedConfigDir, destinationPath));
+  const pathComponents = relativeDestinationPath.split("/").filter((component) => component.length > 0);
+  let currentPath = mergedConfigDir;
+  for (const component of pathComponents) {
+    currentPath = join13(currentPath, component);
+    let currentStats;
     try {
-      await runOpencode(command.args, options2);
+      currentStats = await lstat2(currentPath);
     } catch (error) {
-      handleError(error);
+      const errorCode = error.code;
+      if (errorCode === "ENOENT") {
+        return;
+      }
+      throw createOpencodeOcError("validate", `Failed to inspect overlay destination path (${destinationRelativePath}): ${formatUnknownError(error)}`);
     }
-  });
+    if (currentStats.isSymbolicLink()) {
+      throw createOpencodeOcError("validate", `Overlay destination path contains existing symlink (${destinationRelativePath})`);
+    }
+  }
 }
-async function runOpencode(args, options2) {
-  const projectDir = process.cwd();
-  const resolver = await ConfigResolver.create(projectDir, { profile: options2.profile });
-  const config = resolver.resolve();
-  const profile = resolver.getProfile();
-  if (config.profileName) {
-    logger.info(`Using profile: ${config.profileName}`);
+var projectOverlayPolicySchema = exports_external.object({
+  include: exports_external.array(exports_external.string()).optional(),
+  exclude: exports_external.array(exports_external.string()).optional()
+}).passthrough();
+function validatePolicyPatterns(policyPath, field, patterns) {
+  for (const pattern of patterns) {
+    try {
+      new Glob4(normalizeGlobPattern(pattern));
+    } catch {
+      throw createOpencodeOcError("validate", `Invalid project overlay policy at ${policyPath}: ${field} contains invalid glob pattern "${pattern}"`);
+    }
   }
-  const ocxConfig = profile?.ocx;
-  const shouldRename = options2.rename !== false && ocxConfig?.renameWindow !== false;
-  if (config.profileName) {
-    const profileOpencodePath = getProfileOpencodeConfig(config.profileName);
+}
+async function loadProjectOverlayPolicy(localConfigDir) {
+  if (!localConfigDir) {
+    return { include: [], exclude: [] };
+  }
+  const policyPath = join13(localConfigDir, OCX_CONFIG_FILE);
+  const policyReadPath = await resolveProjectOverlayPolicyReadPath(localConfigDir, policyPath);
+  if (!policyReadPath) {
+    return { include: [], exclude: [] };
+  }
+  let policyText;
+  try {
+    policyText = await readFile2(policyReadPath, "utf8");
+  } catch (error) {
+    throw createOpencodeOcError("read", `Failed to read project overlay policy at ${policyPath}: ${formatUnknownError(error)}`);
+  }
+  const parseErrors = [];
+  const parsedPolicy = parse2(policyText, parseErrors, { allowTrailingComma: true });
+  if (parseErrors.length > 0) {
+    throw createOpencodeOcError("parse", `Failed to parse project overlay policy at ${policyPath}: ${formatJsoncParseError4(parseErrors)}`);
+  }
+  if (!parsedPolicy || typeof parsedPolicy !== "object" || Array.isArray(parsedPolicy)) {
+    throw createOpencodeOcError("validate", `Invalid project overlay policy at ${policyPath}: root must be an object`);
+  }
+  const parsedResult = projectOverlayPolicySchema.safeParse(parsedPolicy);
+  if (!parsedResult.success) {
+    const firstIssue = parsedResult.error.issues[0];
+    const issuePath = firstIssue?.path.length ? firstIssue.path.join(".") : "root";
+    const issueMessage = firstIssue?.message ?? "Invalid project overlay policy";
+    throw createOpencodeOcError("validate", `Invalid project overlay policy at ${policyPath}: ${issuePath} ${issueMessage}`);
+  }
+  const include = parsedResult.data.include ?? [];
+  const exclude = parsedResult.data.exclude ?? [];
+  validatePolicyPatterns(policyPath, "include", include);
+  validatePolicyPatterns(policyPath, "exclude", exclude);
+  return { include, exclude };
+}
+async function resolveProjectOverlayPolicyReadPath(localConfigDir, policyPath) {
+  let policyStats;
+  try {
+    policyStats = await lstat2(policyPath);
+  } catch (error) {
+    const errorCode = error.code;
+    if (errorCode === "ENOENT" || errorCode === "ENOTDIR") {
+      return null;
+    }
+    throw createOpencodeOcError("read", `Failed to inspect project overlay policy at ${policyPath}: ${formatUnknownError(error)}`);
+  }
+  if (!policyStats.isSymbolicLink()) {
+    return policyPath;
+  }
+  let projectConfigRealPath;
+  try {
+    projectConfigRealPath = await realpath(localConfigDir);
+  } catch (error) {
+    throw createOpencodeOcError("validate", `Unable to resolve project config directory ${localConfigDir}: ${formatUnknownError(error)}`);
+  }
+  let policyTargetRealPath;
+  try {
+    policyTargetRealPath = await realpath(policyPath);
+  } catch (error) {
+    const errorCode = error.code;
+    if (errorCode === "ENOENT" || errorCode === "ENOTDIR") {
+      throw createOpencodeOcError("validate", `Broken symlink in project overlay policy: ${policyPath}`);
+    }
+    throw createOpencodeOcError("read", `Failed to inspect project overlay policy symlink at ${policyPath}: ${formatUnknownError(error)}`);
+  }
+  if (!isPathWithin(projectConfigRealPath, policyTargetRealPath)) {
+    throw createOpencodeOcError("validate", `Symlink escapes project overlay policy scope: ${policyPath}`);
+  }
+  return policyTargetRealPath;
+}
+function shouldIncludeOverlayPath(pathValue, policy) {
+  for (const pattern of policy.include) {
+    const glob = new Glob4(normalizeGlobPattern(pattern));
+    if (glob.match(pathValue)) {
+      return true;
+    }
+  }
+  for (const pattern of policy.exclude) {
+    const glob = new Glob4(normalizeGlobPattern(pattern));
+    if (glob.match(pathValue)) {
+      return false;
+    }
+  }
+  return true;
+}
+function planOverlayCopyOperations(candidates, policy) {
+  return candidates.filter((candidate) => shouldIncludeOverlayPath(candidate.overlayRelativePath, policy)).map((candidate) => ({
+    sourcePath: candidate.sourcePath,
+    destinationRelativePath: candidate.overlayRelativePath,
+    sourceSnapshot: candidate.sourceSnapshot
+  }));
+}
+async function rejectSymlinkEntry(projectConfigRealPath, absolutePath, overlayRelativePath) {
+  let targetRealPath;
+  try {
+    targetRealPath = await realpath(absolutePath);
+  } catch (error) {
+    const errorCode = error.code;
+    if (errorCode === "ENOENT" || errorCode === "ENOTDIR") {
+      throw createOpencodeOcError("validate", `Broken symlink in project overlay scope: ${overlayRelativePath}`);
+    }
+    throw createOpencodeOcError("read", `Failed to inspect symlink at ${overlayRelativePath}: ${formatUnknownError(error)}`);
+  }
+  if (!isPathWithin(projectConfigRealPath, targetRealPath)) {
+    throw createOpencodeOcError("validate", `Symlink escapes project overlay scope: ${overlayRelativePath}`);
+  }
+  throw createOpencodeOcError("validate", `Symlink entries are not supported in project overlay scope: ${overlayRelativePath}`);
+}
+async function collectOverlayCandidatesFromPath(projectConfigRealPath, absPath, overlayRelativePath, collector, seams) {
+  let stats;
+  try {
+    stats = await lstat2(absPath);
+  } catch (error) {
+    throw createOpencodeOcError("read", `Failed to inspect project overlay path ${overlayRelativePath}: ${formatUnknownError(error)}`);
+  }
+  if (stats.isSymbolicLink()) {
+    await rejectSymlinkEntry(projectConfigRealPath, absPath, overlayRelativePath);
+  }
+  const discoveredSnapshot = captureOverlaySnapshot(stats);
+  if (stats.isDirectory()) {
+    await seams.beforeDirectoryRead?.({
+      absolutePath: absPath,
+      overlayRelativePath
+    });
+    let children;
+    try {
+      children = await readdir3(absPath);
+    } catch (error) {
+      throw createOpencodeOcError("read", `Failed to read project overlay directory ${overlayRelativePath}: ${formatUnknownError(error)}`);
+    }
+    children.sort((left, right) => left.localeCompare(right));
+    for (const childName of children) {
+      const childAbsolutePath = join13(absPath, childName);
+      const childRelativePath = toPosixPath(join13(overlayRelativePath, childName));
+      await collectOverlayCandidatesFromPath(projectConfigRealPath, childAbsolutePath, childRelativePath, collector, seams);
+    }
+    await assertPathSnapshotUnchanged({
+      absolutePath: absPath,
+      overlayRelativePath,
+      expectedSnapshot: discoveredSnapshot,
+      phase: "overlay discovery",
+      mustRemainDirectory: true
+    });
+    return;
+  }
+  if (!stats.isFile()) {
+    return;
+  }
+  collector.push({
+    sourcePath: absPath,
+    overlayRelativePath: toPosixPath(overlayRelativePath),
+    sourceSnapshot: discoveredSnapshot
+  });
+}
+async function collectOverlayCandidates(projectConfigDir, seams = {}) {
+  let projectConfigRealPath;
+  try {
+    projectConfigRealPath = await realpath(projectConfigDir);
+  } catch (error) {
+    throw createOpencodeOcError("validate", `Unable to resolve project config directory ${projectConfigDir}: ${formatUnknownError(error)}`);
+  }
+  let projectConfigRootStats;
+  try {
+    projectConfigRootStats = await lstat2(projectConfigDir);
+  } catch (error) {
+    throw createOpencodeOcError("validate", `Unable to inspect project overlay root ${projectConfigDir}: ${formatUnknownError(error)}`);
+  }
+  if (!projectConfigRootStats.isDirectory()) {
+    throw createOpencodeOcError("validate", `Project overlay root changed before discovery: ${projectConfigDir}. ${OVERLAY_NATIVE_HELPER_REQUIRED_MESSAGE}`);
+  }
+  const projectConfigRootSnapshot = captureOverlaySnapshot(projectConfigRootStats);
+  const candidates = [];
+  for (const scope of OPENCODE_OVERLAY_SOURCE_SCOPES) {
+    const scopeAbsolutePath = join13(projectConfigDir, scope);
+    await seams.beforeScopeInspect?.({
+      scope,
+      scopeAbsolutePath,
+      projectConfigDir
+    });
+    await assertPathSnapshotUnchanged({
+      absolutePath: projectConfigDir,
+      overlayRelativePath: ".opencode",
+      expectedSnapshot: projectConfigRootSnapshot,
+      phase: "overlay discovery",
+      mustRemainDirectory: true
+    });
+    let scopeStats;
+    try {
+      scopeStats = await lstat2(scopeAbsolutePath);
+    } catch (error) {
+      const errorCode = error.code;
+      if (errorCode === "ENOENT" || errorCode === "ENOTDIR") {
+        continue;
+      }
+      throw createOpencodeOcError("read", `Failed to inspect project overlay scope ${scope}: ${formatUnknownError(error)}`);
+    }
+    if (scopeStats.isSymbolicLink()) {
+      await rejectSymlinkEntry(projectConfigRealPath, scopeAbsolutePath, scope);
+    }
+    await collectOverlayCandidatesFromPath(projectConfigRealPath, scopeAbsolutePath, scope, candidates, seams);
+  }
+  candidates.sort((left, right) => left.overlayRelativePath.localeCompare(right.overlayRelativePath));
+  return candidates;
+}
+function buildOverlayTempPublicationPath(destinationPath) {
+  const destinationDirPath = dirname5(destinationPath);
+  const destinationBaseName = basename3(destinationPath);
+  const atomicSuffix = `${process.pid}-${randomUUID2()}`;
+  return join13(destinationDirPath, `.${destinationBaseName}.ocx-tmp-${atomicSuffix}`);
+}
+async function publishOverlayFileAtomically(sourcePath, destinationPath) {
+  const tempPublicationPath = buildOverlayTempPublicationPath(destinationPath);
+  try {
+    await copyFile(sourcePath, tempPublicationPath);
+    await rename5(tempPublicationPath, destinationPath);
+  } catch (error) {
+    try {
+      await unlink3(tempPublicationPath);
+    } catch {}
+    throw error;
+  }
+}
+async function applyOverlayCopyOperations(operations, mergedConfigDir, seams = {}) {
+  const publishAtomically = seams.publishAtomically ?? publishOverlayFileAtomically;
+  let mergedRootStats;
+  try {
+    mergedRootStats = await lstat2(mergedConfigDir);
+  } catch (error) {
+    throw createOpencodeOcError("validate", `Unable to inspect merged overlay root ${mergedConfigDir}: ${formatUnknownError(error)}`);
+  }
+  if (!mergedRootStats.isDirectory()) {
+    throw createOpencodeOcError("validate", `Merged overlay root is not a directory: ${mergedConfigDir}`);
+  }
+  const mergedRootSnapshot = captureOverlaySnapshot(mergedRootStats);
+  for (const operation of operations) {
+    await seams.beforeSourceVerification?.(operation);
+    if (operation.sourceSnapshot) {
+      await assertPathSnapshotUnchanged({
+        absolutePath: operation.sourcePath,
+        overlayRelativePath: operation.destinationRelativePath,
+        expectedSnapshot: operation.sourceSnapshot,
+        phase: "overlay source verification",
+        mustRemainFile: true
+      });
+    }
+    await assertPathSnapshotUnchanged({
+      absolutePath: mergedConfigDir,
+      overlayRelativePath: ".merged",
+      expectedSnapshot: mergedRootSnapshot,
+      phase: "overlay destination verification",
+      mustRemainDirectory: true,
+      compareContent: false
+    });
+    let destinationPath;
+    try {
+      destinationPath = validatePath(mergedConfigDir, operation.destinationRelativePath);
+    } catch (error) {
+      throw createOpencodeOcError("validate", `Overlay destination path is invalid (${operation.destinationRelativePath}): ${formatUnknownError(error)}`);
+    }
+    await assertSafeOverlayDestinationPath(mergedConfigDir, destinationPath, operation.destinationRelativePath);
+    const destinationParentPath = dirname5(destinationPath);
+    await seams.beforeDestinationParentCreate?.({
+      operation,
+      destinationPath,
+      destinationParentPath
+    });
+    await assertSafeOverlayDestinationPath(mergedConfigDir, destinationPath, operation.destinationRelativePath);
+    try {
+      await mkdir8(destinationParentPath, { recursive: true });
+    } catch (error) {
+      throw createOpencodeOcError("copy", `Failed to copy overlay file ${operation.destinationRelativePath}: ${formatUnknownError(error)}`);
+    }
+    await assertSafeOverlayDestinationPath(mergedConfigDir, destinationPath, operation.destinationRelativePath);
+    let destinationParentStats;
+    try {
+      destinationParentStats = await lstat2(destinationParentPath);
+    } catch (error) {
+      throw createOpencodeOcError("validate", `Failed to inspect overlay destination parent (${operation.destinationRelativePath}): ${formatUnknownError(error)}`);
+    }
+    if (!destinationParentStats.isDirectory()) {
+      throw createOpencodeOcError("validate", `Overlay destination parent changed before publish (${operation.destinationRelativePath}). ${OVERLAY_NATIVE_HELPER_REQUIRED_MESSAGE}`);
+    }
+    const destinationParentSnapshot = captureOverlaySnapshot(destinationParentStats);
+    await seams.beforeDestinationPublish?.({
+      operation,
+      destinationPath,
+      destinationParentPath
+    });
+    await assertPathSnapshotUnchanged({
+      absolutePath: mergedConfigDir,
+      overlayRelativePath: ".merged",
+      expectedSnapshot: mergedRootSnapshot,
+      phase: "overlay destination publish",
+      mustRemainDirectory: true,
+      compareContent: false
+    });
+    await assertPathSnapshotUnchanged({
+      absolutePath: destinationParentPath,
+      overlayRelativePath: operation.destinationRelativePath,
+      expectedSnapshot: destinationParentSnapshot,
+      phase: "overlay destination publish",
+      mustRemainDirectory: true,
+      compareContent: false
+    });
+    await assertSafeOverlayDestinationPath(mergedConfigDir, destinationPath, operation.destinationRelativePath);
+    try {
+      await publishAtomically(operation.sourcePath, destinationPath);
+    } catch (error) {
+      if (error instanceof ConfigError) {
+        throw error;
+      }
+      throw createOpencodeOcError("copy", `Failed to copy overlay file ${operation.destinationRelativePath}: ${formatUnknownError(error)}`);
+    }
+  }
+}
+async function copyProfileBaseToMergedDir(profileDir, mergedConfigDir) {
+  let profileEntries;
+  try {
+    profileEntries = await readdir3(profileDir);
+  } catch (error) {
+    throw createOpencodeOcError("copy", `Failed to read profile directory ${profileDir}: ${formatUnknownError(error)}`);
+  }
+  for (const entryName of profileEntries) {
+    const sourcePath = join13(profileDir, entryName);
+    const destinationPath = join13(mergedConfigDir, entryName);
+    try {
+      await cp2(sourcePath, destinationPath, { recursive: true, force: true, errorOnExist: false });
+    } catch (error) {
+      throw createOpencodeOcError("copy", `Failed to copy profile base file ${entryName}: ${formatUnknownError(error)}`);
+    }
+  }
+}
+async function cleanupMergedConfigDir(mergedConfigDir) {
+  try {
+    await rm5(mergedConfigDir, { recursive: true, force: true });
+  } catch (error) {
+    throw createOpencodeOcError("cleanup", `Failed to remove temporary merged config directory ${mergedConfigDir}: ${formatUnknownError(error)}`);
+  }
+}
+function toOverlaySourceRelativePath(projectConfigDir, sourcePath) {
+  const relativeSourcePath = toPosixPath(relative6(projectConfigDir, sourcePath));
+  if (!relativeSourcePath || relativeSourcePath === ".") {
+    throw createOpencodeOcError("validate", `Overlay source path failed relative parsing: ${sourcePath}`);
+  }
+  if (relativeSourcePath === ".." || relativeSourcePath.startsWith("../") || isAbsolute7(relativeSourcePath)) {
+    throw createOpencodeOcError("validate", `Overlay source path escapes project overlay scope: ${sourcePath}`);
+  }
+  return relativeSourcePath;
+}
+function buildOverlayTransactionManifest(projectConfigDir, operations) {
+  const parsedOperations = operations.map((operation) => {
+    if (!operation.sourceSnapshot) {
+      throw createOpencodeOcError("validate", `Overlay source snapshot missing for ${operation.destinationRelativePath}. ${OVERLAY_NATIVE_HELPER_REQUIRED_MESSAGE}`);
+    }
+    return {
+      sourceRelativePath: toOverlaySourceRelativePath(projectConfigDir, operation.sourcePath),
+      destinationRelativePath: operation.destinationRelativePath,
+      sourceSnapshot: operation.sourceSnapshot
+    };
+  });
+  return {
+    version: OVERLAY_TRANSACTION_MANIFEST_VERSION,
+    projectConfigDir,
+    operations: parsedOperations
+  };
+}
+function resolveOverlayNativeTransactionHelper() {
+  return null;
+}
+async function applyOverlayTransactionManifestWithJs(options2) {
+  const operations = options2.manifest.operations.map((operation) => ({
+    sourcePath: validatePath(options2.manifest.projectConfigDir, operation.sourceRelativePath),
+    destinationRelativePath: operation.destinationRelativePath,
+    sourceSnapshot: operation.sourceSnapshot
+  }));
+  await applyOverlayCopyOperations(operations, options2.mergedConfigDir, options2.copySeams);
+}
+async function executeOverlayMergeTransaction(options2) {
+  if (options2.manifest.operations.length === 0) {
+    return "best-effort-js";
+  }
+  const nativeHelper = options2.nativeHelper ?? resolveOverlayNativeTransactionHelper();
+  if (nativeHelper) {
+    await nativeHelper.applyManifest(options2.manifest, options2.mergedConfigDir);
+    return "native-fd";
+  }
+  if (options2.hardeningMode === "native-fd-required") {
+    throw createOpencodeOcError("validate", `Native fd helper required for overlay merge, but none is available in this Bun/Node runtime. ${OVERLAY_NATIVE_HELPER_REQUIRED_MESSAGE}`);
+  }
+  await applyOverlayTransactionManifestWithJs({
+    manifest: options2.manifest,
+    mergedConfigDir: options2.mergedConfigDir,
+    copySeams: options2.copySeams
+  });
+  return "best-effort-js";
+}
+async function resolveProjectOverlayConfigDir(localConfigDir) {
+  const projectRootDir = dirname5(localConfigDir);
+  let projectRealPath;
+  try {
+    projectRealPath = await realpath(projectRootDir);
+  } catch (error) {
+    throw createOpencodeOcError("validate", `Unable to resolve project directory ${projectRootDir}: ${formatUnknownError(error)}`);
+  }
+  let localConfigRealPath;
+  try {
+    localConfigRealPath = await realpath(localConfigDir);
+  } catch (error) {
+    throw createOpencodeOcError("validate", `Unable to resolve project config directory ${localConfigDir}: ${formatUnknownError(error)}`);
+  }
+  if (!isPathWithin(projectRealPath, localConfigRealPath)) {
+    throw createOpencodeOcError("validate", `Project .opencode root resolves outside project directory: ${localConfigDir}`);
+  }
+  return localConfigRealPath;
+}
+function toPrimaryPrepareError(error) {
+  if (error instanceof ConfigError) {
+    return error;
+  }
+  return createOpencodeOcError("copy", `Failed to prepare temporary merged config directory: ${formatUnknownError(error)}`);
+}
+async function prepareMergedConfigDirForProfile(options2) {
+  const localConfigDir = findLocalConfigDir(options2.projectDir);
+  const hardeningMode = options2.hardeningMode ?? "best-effort-js";
+  let mergedConfigDir = null;
+  try {
+    mergedConfigDir = await mkdtemp(join13(tmpdir(), OPENCODE_MERGED_DIR_PREFIX));
+    await copyProfileBaseToMergedDir(options2.profileDir, mergedConfigDir);
+    let hardeningLevel = "best-effort-js";
+    if (localConfigDir) {
+      const projectOverlayConfigDir = await resolveProjectOverlayConfigDir(localConfigDir);
+      const policy = await loadProjectOverlayPolicy(projectOverlayConfigDir);
+      const candidates = await collectOverlayCandidates(projectOverlayConfigDir, options2.seams?.collection);
+      const copyPlan = planOverlayCopyOperations(candidates, policy);
+      const manifest = buildOverlayTransactionManifest(projectOverlayConfigDir, copyPlan);
+      hardeningLevel = await executeOverlayMergeTransaction({
+        manifest,
+        mergedConfigDir,
+        hardeningMode,
+        copySeams: options2.seams?.copy,
+        nativeHelper: options2.seams?.nativeHelper
+      });
+    }
+    const preparedPath = mergedConfigDir;
+    return {
+      path: preparedPath,
+      cleanup: () => cleanupMergedConfigDir(preparedPath),
+      hardeningLevel
+    };
+  } catch (error) {
+    const primaryError = toPrimaryPrepareError(error);
+    if (mergedConfigDir) {
+      try {
+        await cleanupMergedConfigDir(mergedConfigDir);
+      } catch (cleanupError) {
+        primaryError.message = `${primaryError.message}
+Cleanup warning: ${formatUnknownError(cleanupError)}`;
+      }
+    }
+    throw primaryError;
+  }
+}
+
+// src/commands/opencode.ts
+function dedupeLastWins(items) {
+  const seen = new Set;
+  const result = [];
+  for (let i = items.length - 1;i >= 0; i--) {
+    const item = items[i];
+    if (!seen.has(item)) {
+      seen.add(item);
+      result.unshift(item);
+    }
+  }
+  return result;
+}
+function resolveOpenCodeBinary(opts) {
+  return opts.configBin ?? opts.envBin ?? "opencode";
+}
+function buildOpenCodeEnv(opts) {
+  const hasProfile = Boolean(opts.profileName);
+  const {
+    OPENCODE_DISABLE_PROJECT_CONFIG: _inheritedDisableProjectConfig,
+    ...baseEnvWithoutDisableProjectConfig
+  } = opts.baseEnv;
+  return {
+    ...baseEnvWithoutDisableProjectConfig,
+    ...hasProfile && { OPENCODE_DISABLE_PROJECT_CONFIG: "true" },
+    OPENCODE_CONFIG_DIR: opts.configDir ?? (hasProfile ? getProfileDir(opts.profileName) : getGlobalConfigPath()),
+    ...opts.configContent && { OPENCODE_CONFIG_CONTENT: opts.configContent },
+    ...opts.profileName && { OCX_PROFILE: opts.profileName }
+  };
+}
+function registerOpencodeCommand(program2) {
+  program2.command("oc").alias("opencode").description("Launch OpenCode with resolved configuration").option("-p, --profile <name>", "Use specific profile").option("--no-rename", "Disable terminal/tmux window renaming").allowUnknownOption().allowExcessArguments(true).action(async (options2, command) => {
+    try {
+      await runOpencode(command.args, options2);
+    } catch (error) {
+      handleError(error);
+    }
+  });
+}
+async function runOpencode(args, options2) {
+  const projectDir = process.cwd();
+  const resolver = await ConfigResolver.create(projectDir, { profile: options2.profile });
+  const config = resolver.resolve();
+  const profile = resolver.getProfile();
+  if (config.profileName) {
+    logger.info(`Using profile: ${config.profileName}`);
+  }
+  const ocxConfig = profile?.ocx;
+  const shouldRename = options2.rename !== false && ocxConfig?.renameWindow !== false;
+  if (config.profileName) {
+    const profileOpencodePath = getProfileOpencodeConfig(config.profileName);
     const profileOpencodeFile = Bun.file(profileOpencodePath);
     const hasOpencodeConfig = await profileOpencodeFile.exists();
     if (!hasOpencodeConfig) {
@@ -17217,73 +18215,111 @@ async function runOpencode(args, options2) {
     instructions: dedupedInstructions.length > 0 ? dedupedInstructions : undefined
   } : undefined;
   let proc = null;
+  let mergedConfig = null;
+  let primaryFailure = null;
+  let childExitCode = null;
+  let preSpawnSignalExitCode = null;
   const sigintHandler = () => {
     if (proc) {
       proc.kill("SIGINT");
     } else {
-      if (shouldRename) {
-        restoreTerminalTitle();
-      }
-      process.exit(130);
+      preSpawnSignalExitCode = 130;
     }
   };
   const sigtermHandler = () => {
     if (proc) {
       proc.kill("SIGTERM");
     } else {
-      if (shouldRename) {
-        restoreTerminalTitle();
-      }
-      process.exit(143);
+      preSpawnSignalExitCode = 143;
     }
   };
-  process.on("SIGINT", sigintHandler);
-  process.on("SIGTERM", sigtermHandler);
   const exitHandler = () => {
     if (shouldRename) {
       restoreTerminalTitle();
     }
   };
-  process.on("exit", exitHandler);
-  if (shouldRename) {
-    saveTerminalTitle();
-    const gitInfo = await getGitInfo(projectDir);
-    setTerminalName(formatTerminalName(projectDir, config.profileName ?? "default", gitInfo));
-  }
-  const bin = resolveOpenCodeBinary({
-    configBin: ocxConfig?.bin,
-    envBin: process.env.OPENCODE_BIN
-  });
-  const configContent = configToPass ? JSON.stringify(configToPass) : undefined;
-  proc = Bun.spawn({
-    cmd: [bin, ...args],
-    cwd: projectDir,
-    env: buildOpenCodeEnv({
-      baseEnv: process.env,
-      profileName: config.profileName ?? undefined,
-      configContent
-    }),
-    stdin: "inherit",
-    stdout: "inherit",
-    stderr: "inherit"
-  });
   try {
-    const exitCode = await proc.exited;
-    process.off("SIGINT", sigintHandler);
-    process.off("SIGTERM", sigtermHandler);
-    process.off("exit", exitHandler);
+    process.on("SIGINT", sigintHandler);
+    process.on("SIGTERM", sigtermHandler);
+    process.on("exit", exitHandler);
+    if (preSpawnSignalExitCode !== null) {
+      childExitCode = preSpawnSignalExitCode;
+      return;
+    }
+    if (config.profileName) {
+      mergedConfig = await prepareMergedConfigDirForProfile({
+        projectDir,
+        profileDir: getProfileDir(config.profileName)
+      });
+    }
+    if (preSpawnSignalExitCode !== null) {
+      childExitCode = preSpawnSignalExitCode;
+      return;
+    }
     if (shouldRename) {
-      restoreTerminalTitle();
+      saveTerminalTitle();
+      const gitInfo = await getGitInfo(projectDir);
+      if (preSpawnSignalExitCode !== null) {
+        childExitCode = preSpawnSignalExitCode;
+        return;
+      }
+      setTerminalName(formatTerminalName(projectDir, config.profileName ?? "default", gitInfo));
+    }
+    if (preSpawnSignalExitCode !== null) {
+      childExitCode = preSpawnSignalExitCode;
+      return;
     }
-    process.exit(exitCode);
+    const bin = resolveOpenCodeBinary({
+      configBin: ocxConfig?.bin,
+      envBin: process.env.OPENCODE_BIN
+    });
+    const configContent = configToPass ? JSON.stringify(configToPass) : undefined;
+    try {
+      proc = Bun.spawn({
+        cmd: [bin, ...args],
+        cwd: projectDir,
+        env: buildOpenCodeEnv({
+          baseEnv: process.env,
+          profileName: config.profileName ?? undefined,
+          configDir: mergedConfig?.path,
+          configContent
+        }),
+        stdin: "inherit",
+        stdout: "inherit",
+        stderr: "inherit"
+      });
+    } catch (error) {
+      throw createOpencodeOcError("spawn", `Failed to launch OpenCode binary "${bin}": ${error instanceof Error ? error.message : String(error)}`);
+    }
+    childExitCode = await proc.exited;
   } catch (error) {
+    primaryFailure = error instanceof Error ? error : createOpencodeOcError("spawn", `OpenCode process failed: ${String(error)}`);
+  } finally {
     process.off("SIGINT", sigintHandler);
     process.off("SIGTERM", sigtermHandler);
     process.off("exit", exitHandler);
     if (shouldRename) {
       restoreTerminalTitle();
     }
-    throw error;
+    if (mergedConfig) {
+      try {
+        await mergedConfig.cleanup();
+      } catch (cleanupError) {
+        const hasPrimaryFailure = primaryFailure !== null || preSpawnSignalExitCode !== null || childExitCode !== null && childExitCode !== 0;
+        if (hasPrimaryFailure) {
+          logger.warn(`Cleanup warning: ${cleanupError instanceof Error ? cleanupError.message : String(cleanupError)}`);
+        } else {
+          const cleanupFailure = cleanupError instanceof Error ? cleanupError : createOpencodeOcError("cleanup", `Failed to remove temporary merged config directory: ${String(cleanupError)}`);
+          primaryFailure = cleanupFailure;
+        }
+      }
+    }
+  }
+  if (primaryFailure) {
+    throw primaryFailure;
+  }
+  if (childExitCode !== null) {
+    process.exit(childExitCode);
   }
 }
 
@@ -17292,8 +18328,8 @@ init_errors2();
 
 // src/commands/profile/install-from-registry.ts
 import { existsSync as existsSync14 } from "fs";
-import { mkdir as mkdir8, mkdtemp, rename as rename5, rm as rm5, writeFile as writeFile4 } from "fs/promises";
-import { dirname as dirname5, join as join12, relative as relative6 } from "path";
+import { mkdir as mkdir9, mkdtemp as mkdtemp2, rename as rename6, rm as rm6, writeFile as writeFile4 } from "fs/promises";
+import { dirname as dirname6, join as join14, relative as relative7 } from "path";
 init_fetcher();
 init_registry();
 init_errors2();
@@ -17302,6 +18338,112 @@ function formatProfileRollbackCleanupWarning(action, targetPath, error) {
   const errorMessage = error instanceof Error ? error.message : String(error);
   return `${action} "${targetPath}" (${errorMessage})`;
 }
+function buildPackumentUrl(registryUrl, qualifiedName) {
+  const [registryName, componentName] = qualifiedName.split("/");
+  if (!registryName || !componentName) {
+    return;
+  }
+  return `${normalizeRegistryUrl(registryUrl)}/components/${componentName}.json`;
+}
+function parseQualifiedNameParts(qualifiedName) {
+  if (!qualifiedName)
+    return null;
+  const [registryName, componentName, ...extraParts] = qualifiedName.split("/");
+  if (!registryName || !componentName || extraParts.length > 0) {
+    return null;
+  }
+  return { registryName, componentName };
+}
+function inferDependencyFromErrorUrl(errorUrl, registries) {
+  if (!errorUrl) {
+    return {};
+  }
+  let componentName;
+  try {
+    const parsedErrorUrl = new URL(errorUrl);
+    const packumentMatch = parsedErrorUrl.pathname.match(/(?:^|\/)components\/([^/]+)\.json$/);
+    if (packumentMatch?.[1]) {
+      componentName = decodeURIComponent(packumentMatch[1]);
+    } else {
+      const fileContentMatch = parsedErrorUrl.pathname.match(/(?:^|\/)components\/([^/]+)\/.+$/);
+      if (fileContentMatch?.[1]) {
+        componentName = decodeURIComponent(fileContentMatch[1]);
+      }
+    }
+  } catch {}
+  const normalizedErrorUrl = normalizeRegistryUrl(errorUrl);
+  let registryName;
+  let matchedPrefixLength = -1;
+  for (const [candidateRegistryName, registryConfig] of Object.entries(registries)) {
+    const normalizedRegistryUrl = normalizeRegistryUrl(registryConfig.url);
+    const isMatch = normalizedErrorUrl === normalizedRegistryUrl || normalizedErrorUrl.startsWith(`${normalizedRegistryUrl}/`);
+    if (!isMatch || normalizedRegistryUrl.length <= matchedPrefixLength) {
+      continue;
+    }
+    registryName = candidateRegistryName;
+    matchedPrefixLength = normalizedRegistryUrl.length;
+  }
+  return { registryName, componentName };
+}
+function resolveDependencyDiagnosticsContext(options2) {
+  const fallbackQualifiedName = options2.depRefs[0] ?? `${options2.namespace}/${options2.component}`;
+  const knownRegistries = {
+    ...options2.profileRegistries,
+    ...options2.profileRegistries[options2.namespace] ? {} : {
+      [options2.namespace]: {
+        url: options2.registryUrl
+      }
+    }
+  };
+  let registryName = options2.error.registryName;
+  let qualifiedName = options2.error.qualifiedName;
+  const qualifiedNameParts = parseQualifiedNameParts(qualifiedName);
+  if (!registryName && qualifiedNameParts) {
+    registryName = qualifiedNameParts.registryName;
+  }
+  const qualifiedComponentName = qualifiedNameParts?.componentName;
+  const bareComponentNameFromError = qualifiedName && !qualifiedNameParts && !qualifiedName.includes("/") ? qualifiedName : undefined;
+  const inferred = inferDependencyFromErrorUrl(options2.error.url, knownRegistries);
+  if (!registryName && inferred.registryName) {
+    registryName = inferred.registryName;
+  }
+  const resolvedComponentName = qualifiedComponentName ?? bareComponentNameFromError ?? inferred.componentName;
+  if ((!qualifiedName || !qualifiedNameParts) && registryName && resolvedComponentName) {
+    qualifiedName = `${registryName}/${resolvedComponentName}`;
+  }
+  if (!qualifiedName) {
+    qualifiedName = fallbackQualifiedName;
+  }
+  if (!registryName) {
+    registryName = parseQualifiedNameParts(qualifiedName)?.registryName ?? options2.namespace;
+  }
+  const fallbackRegistryUrl = knownRegistries[registryName]?.url || (registryName === options2.namespace ? options2.registryUrl : undefined);
+  return {
+    registryName,
+    qualifiedName,
+    fallbackUrl: options2.error.url || (fallbackRegistryUrl ? buildPackumentUrl(fallbackRegistryUrl, qualifiedName) : undefined)
+  };
+}
+function withRegistryDiagnostics(error, context) {
+  const phase = error.phase ?? context.fallbackPhase;
+  const url2 = error.url ?? context.fallbackUrl;
+  const diagnostics = [
+    `phase: ${phase}`,
+    `qualifiedName: ${context.qualifiedName}`,
+    `registryContext: ${context.registryContext}`,
+    `registryName: ${context.registryName}`,
+    ...url2 ? [`url: ${url2}`] : []
+  ];
+  return new NetworkError(`${error.message} (${diagnostics.join(", ")})`, {
+    url: url2,
+    status: error.status,
+    statusText: error.statusText,
+    phase,
+    qualifiedName: context.qualifiedName,
+    registryContext: context.registryContext,
+    registryName: context.registryName
+  });
+}
 function resolveEmbeddedProfileTarget(rawTarget, stagingDir) {
   if (!rawTarget.startsWith(".opencode/")) {
     throw new ValidationError(`Invalid embedded target "${rawTarget}": expected .opencode/ prefix for embedded profile files.`);
@@ -17319,7 +18461,7 @@ function resolveEmbeddedProfileTarget(rawTarget, stagingDir) {
     }
     throw error;
   }
-  const safeRelativeTarget = relative6(stagingDir, safeAbsolutePath).replace(/\\/g, "/");
+  const safeRelativeTarget = relative7(stagingDir, safeAbsolutePath).replace(/\\/g, "/");
   if (safeRelativeTarget === "." || safeRelativeTarget === "") {
     throw new ValidationError(`Invalid embedded target "${rawTarget}": target must resolve to a file path.`);
   }
@@ -17352,6 +18494,15 @@ async function installProfileFromRegistry(options2) {
     manifest = await fetchComponent(registryUrl, component);
   } catch (error) {
     fetchSpin?.fail(`Failed to fetch ${qualifiedName}`);
+    if (error instanceof NetworkError) {
+      throw withRegistryDiagnostics(error, {
+        registryContext: "source",
+        registryName: namespace,
+        qualifiedName,
+        fallbackPhase: "packument-fetch",
+        fallbackUrl: buildPackumentUrl(registryUrl, qualifiedName)
+      });
+    }
     if (error instanceof NotFoundError) {
       throw new NotFoundError(`Profile component "${qualifiedName}" not found in registry.
 
@@ -17386,8 +18537,8 @@ async function installProfileFromRegistry(options2) {
   }
   filesSpin?.succeed(`Downloaded ${normalized.files.length} files`);
   const profilesDir = getProfilesDir();
-  await mkdir8(profilesDir, { recursive: true, mode: 448 });
-  const stagingDir = await mkdtemp(join12(profilesDir, ".staging-"));
+  await mkdir9(profilesDir, { recursive: true, mode: 448 });
+  const stagingDir = await mkdtemp2(join14(profilesDir, ".staging-"));
   let profilePromoted = false;
   let installCommitted = false;
   try {
@@ -17396,7 +18547,7 @@ async function installProfileFromRegistry(options2) {
     const plannedWrites = new Map;
     for (const file of profileFiles) {
       const resolvedTarget = resolveComponentTargetRoot(file.target, stagingDir);
-      const targetPath = join12(stagingDir, resolvedTarget);
+      const targetPath = join14(stagingDir, resolvedTarget);
       registerPlannedWriteOrThrow(plannedWrites, {
         absolutePath: targetPath,
         relativePath: resolvedTarget,
@@ -17407,7 +18558,7 @@ async function installProfileFromRegistry(options2) {
     for (const file of embeddedFiles) {
       const target = resolveEmbeddedProfileTarget(file.target, stagingDir);
       const resolvedTarget = resolveComponentTargetRoot(target, stagingDir);
-      const targetPath = join12(stagingDir, resolvedTarget);
+      const targetPath = join14(stagingDir, resolvedTarget);
       registerPlannedWriteOrThrow(plannedWrites, {
         absolutePath: targetPath,
         relativePath: resolvedTarget,
@@ -17417,9 +18568,9 @@ async function installProfileFromRegistry(options2) {
     }
     for (const plannedWrite of plannedWrites.values()) {
       const targetPath = plannedWrite.absolutePath;
-      const targetDir = dirname5(targetPath);
+      const targetDir = dirname6(targetPath);
       if (!existsSync14(targetDir)) {
-        await mkdir8(targetDir, { recursive: true });
+        await mkdir9(targetDir, { recursive: true });
       }
       await writeFile4(targetPath, plannedWrite.content);
     }
@@ -17431,20 +18582,20 @@ async function installProfileFromRegistry(options2) {
     });
     const renameSpin = quiet ? null : createSpinner({ text: "Moving to profile directory..." });
     renameSpin?.start();
-    const profilesDir2 = dirname5(profileDir);
+    const profilesDir2 = dirname6(profileDir);
     if (!existsSync14(profilesDir2)) {
-      await mkdir8(profilesDir2, { recursive: true, mode: 448 });
+      await mkdir9(profilesDir2, { recursive: true, mode: 448 });
     }
-    await rename5(stagingDir, profileDir);
+    await rename6(stagingDir, profileDir);
     profilePromoted = true;
     renameSpin?.succeed("Profile installed");
     if (manifest.dependencies.length > 0) {
       const depsSpin = quiet ? null : createSpinner({ text: "Installing dependencies..." });
       depsSpin?.start();
+      const depRefs = manifest.dependencies.map((dep) => dep.includes("/") ? dep : `${namespace}/${dep}`);
+      let profileRegistries = {};
       try {
-        const depRefs = manifest.dependencies.map((dep) => dep.includes("/") ? dep : `${namespace}/${dep}`);
-        const profileOcxConfigPath = join12(profileDir, "ocx.jsonc");
-        let profileRegistries = {};
+        const profileOcxConfigPath = join14(profileDir, "ocx.jsonc");
         if (existsSync14(profileOcxConfigPath)) {
           const profileOcxFile = Bun.file(profileOcxConfigPath);
           const profileOcxContent = await profileOcxFile.text();
@@ -17465,6 +18616,23 @@ async function installProfileFromRegistry(options2) {
         depsSpin?.succeed(`Installed ${manifest.dependencies.length} dependencies`);
       } catch (error) {
         depsSpin?.fail("Failed to install dependencies");
+        if (error instanceof NetworkError) {
+          const dependencyDiagnosticsContext = resolveDependencyDiagnosticsContext({
+            error,
+            depRefs,
+            namespace,
+            component,
+            registryUrl,
+            profileRegistries
+          });
+          throw withRegistryDiagnostics(error, {
+            registryContext: "dependency",
+            registryName: dependencyDiagnosticsContext.registryName,
+            qualifiedName: dependencyDiagnosticsContext.qualifiedName,
+            fallbackPhase: "packument-fetch",
+            fallbackUrl: dependencyDiagnosticsContext.fallbackUrl
+          });
+        }
         throw error;
       }
     }
@@ -17486,7 +18654,7 @@ async function installProfileFromRegistry(options2) {
     const cleanupWarnings = [];
     try {
       if (existsSync14(stagingDir)) {
-        await rm5(stagingDir, { recursive: true });
+        await rm6(stagingDir, { recursive: true });
       }
     } catch (cleanupError) {
       cleanupWarnings.push(formatProfileRollbackCleanupWarning("Profile add rollback cleanup warning: failed to remove staging directory", stagingDir, cleanupError));
@@ -17494,7 +18662,7 @@ async function installProfileFromRegistry(options2) {
     if (profilePromoted && !installCommitted) {
       try {
         if (existsSync14(profileDir)) {
-          await rm5(profileDir, { recursive: true, force: true });
+          await rm6(profileDir, { recursive: true, force: true });
         }
       } catch (cleanupError) {
         cleanupWarnings.push(formatProfileRollbackCleanupWarning("Profile add rollback cleanup warning: failed to remove promoted profile", profileDir, cleanupError));
@@ -17906,7 +19074,7 @@ function registerProfileCommand(program2) {
 
 // src/commands/registry.ts
 import { existsSync as existsSync15 } from "fs";
-import { dirname as dirname6, join as join13 } from "path";
+import { dirname as dirname7, join as join15 } from "path";
 init_errors2();
 async function runRegistryAddCore2(url2, options2, callbacks) {
   if (callbacks.isLocked?.()) {
@@ -18033,7 +19201,7 @@ async function resolveRegistryTarget(options2, command, cwd) {
     return {
       scope: "profile",
       configPath,
-      configDir: dirname6(configPath),
+      configDir: dirname7(configPath),
       targetLabel: `profile '${options2.profile}' config`
     };
   }
@@ -18041,7 +19209,7 @@ async function resolveRegistryTarget(options2, command, cwd) {
     const configDir = getGlobalConfigPath();
     return {
       scope: "global",
-      configPath: join13(configDir, "ocx.jsonc"),
+      configPath: join15(configDir, "ocx.jsonc"),
       configDir,
       targetLabel: "global config"
     };
@@ -18050,7 +19218,7 @@ async function resolveRegistryTarget(options2, command, cwd) {
   return {
     scope: "local",
     configPath: found.path,
-    configDir: found.exists ? dirname6(found.path) : join13(cwd, ".opencode"),
+    configDir: found.exists ? dirname7(found.path) : join15(cwd, ".opencode"),
     targetLabel: "local config"
   };
 }
@@ -18171,7 +19339,7 @@ function registerRegistryCommand(program2) {
 
 // src/commands/remove.ts
 import { realpathSync } from "fs";
-import { rm as rm6 } from "fs/promises";
+import { rm as rm7 } from "fs/promises";
 import { sep } from "path";
 
 // src/utils/component-ref-resolver.ts
@@ -18424,7 +19592,7 @@ ${details}`);
           }
           continue;
         }
-        await rm6(deleteTarget, { force: true });
+        await rm7(deleteTarget, { force: true });
         if (options2.verbose) {
           logger.info(`  \u2713 Removed ${fileEntry.path}`);
         }
@@ -18676,11 +19844,11 @@ function tildify(absolutePath) {
 function getRelativePathIfContained(parent, child) {
   const normalizedParent = path8.normalize(parent);
   const normalizedChild = path8.normalize(child);
-  const relative7 = path8.relative(normalizedParent, normalizedChild);
-  if (relative7.startsWith("..") || path8.isAbsolute(relative7)) {
+  const relative8 = path8.relative(normalizedParent, normalizedChild);
+  if (relative8.startsWith("..") || path8.isAbsolute(relative8)) {
     return null;
   }
-  return relative7;
+  return relative8;
 }
 function isLexicallyInside(root, target) {
   return getRelativePathIfContained(root, target) !== null;
@@ -19180,7 +20348,7 @@ init_errors2();
 
 // src/self-update/version-provider.ts
 class BuildTimeVersionProvider {
-  version = "2.0.0";
+  version = "2.0.1";
 }
 var defaultVersionProvider = new BuildTimeVersionProvider;
 
@@ -19565,13 +20733,16 @@ function registerSelfCommand(program2) {
 }
 
 // src/commands/update.ts
-import { randomUUID as randomUUID2 } from "crypto";
+import { randomUUID as randomUUID3 } from "crypto";
 import { existsSync as existsSync18 } from "fs";
-import { mkdir as mkdir9, rename as rename6, rm as rm7, stat as stat4, writeFile as writeFile5 } from "fs/promises";
-import { dirname as dirname7, join as join14 } from "path";
+import { mkdir as mkdir10, rename as rename7, rm as rm8, stat as stat4, writeFile as writeFile5 } from "fs/promises";
+import { dirname as dirname8, join as join16 } from "path";
 init_fetcher();
 init_registry();
 init_errors2();
+function formatAddCommandHint(component, options2) {
+  return `ocx add${options2.global ? " --global" : ""} ${component}`;
+}
 function resolveUpdateFailureMessage(phase) {
   return phase === "apply" ? "Failed to update components" : "Failed to check for updates";
 }
@@ -19579,6 +20750,7 @@ function registerUpdateCommand(program2) {
   const cmd = program2.command("update [components...]").description("Update installed components");
   addCommonOptions(cmd);
   addVerboseOption(cmd);
+  addGlobalOption(cmd);
   cmd.option("--all", "Update all installed components").option("--registry <name>", "Update all components from a specific registry").option("--dry-run", "Preview changes without applying").action(async (components, options2) => {
     try {
       await runUpdate(components, options2);
@@ -19589,7 +20761,7 @@ function registerUpdateCommand(program2) {
 }
 async function runUpdate(componentNames, options2) {
   const cwd = options2.cwd ?? process.cwd();
-  const provider = await LocalConfigProvider.requireInitialized(cwd);
+  const provider = options2.global ? await GlobalConfigProvider.requireInitialized() : await LocalConfigProvider.requireInitialized(cwd);
   await runUpdateCore(componentNames, options2, provider);
 }
 async function runUpdateCore(componentNames, options2, provider, fileOps) {
@@ -19600,9 +20772,13 @@ async function runUpdateCore(componentNames, options2, provider, fileOps) {
   const receipt = await readReceipt(provider.cwd);
   if (!receipt || Object.keys(receipt.installed).length === 0) {
     if (componentNames.length > 0) {
-      throw new NotFoundError(`Component '${componentNames[0]}' is not installed. Run 'ocx add ${componentNames[0]}' first.`);
+      const requestedComponent = componentNames[0];
+      if (!requestedComponent) {
+        throw new Error("Unexpected: component name missing despite non-empty componentNames");
+      }
+      throw new NotFoundError(`Component '${requestedComponent}' is not installed. Run '${formatAddCommandHint(requestedComponent, options2)}' first.`);
     }
-    throw new NotFoundError("No components installed. Run 'ocx add <component>' first.");
+    throw new NotFoundError(`No components installed. Run '${formatAddCommandHint("<component>", options2)}' first.`);
   }
   const hasComponents = componentNames.length > 0;
   const hasAll = options2.all === true;
@@ -19725,7 +20901,7 @@ async function runUpdateCore(componentNames, options2, provider, fileOps) {
           throw new ValidationError(`File "${file.path}" not found in component manifest for "${update.registryName}/${update.name}".`);
         }
         const resolvedTarget = resolveTargetPath(fileObj.target, isFlattened, provider.cwd);
-        const targetPath = join14(provider.cwd, resolvedTarget);
+        const targetPath = join16(provider.cwd, resolvedTarget);
         registerPlannedWriteOrThrow(plannedWrites, {
           absolutePath: targetPath,
           relativePath: resolvedTarget,
@@ -19814,7 +20990,7 @@ async function applyPreparedUpdatesAtomically(preparedUpdates, options2) {
   const appliedWrites = [];
   const tempPaths = new Set;
   let finalized = false;
-  const renameFile = options2.fileOps?.rename ?? rename6;
+  const renameFile = options2.fileOps?.rename ?? rename7;
   const rollback = async () => {
     if (finalized) {
       return;
@@ -19822,20 +20998,20 @@ async function applyPreparedUpdatesAtomically(preparedUpdates, options2) {
     finalized = true;
     for (const tempPath of tempPaths) {
       try {
-        await rm7(tempPath, { force: true });
+        await rm8(tempPath, { force: true });
       } catch {}
     }
     for (const appliedWrite of [...appliedWrites].reverse()) {
       try {
         if (appliedWrite.backupPath) {
           if (existsSync18(appliedWrite.targetPath)) {
-            await rm7(appliedWrite.targetPath, { force: true, recursive: true });
+            await rm8(appliedWrite.targetPath, { force: true, recursive: true });
           }
           if (existsSync18(appliedWrite.backupPath)) {
             await renameFile(appliedWrite.backupPath, appliedWrite.targetPath);
           }
         } else if (existsSync18(appliedWrite.targetPath)) {
-          await rm7(appliedWrite.targetPath, { force: true, recursive: true });
+          await rm8(appliedWrite.targetPath, { force: true, recursive: true });
         }
       } catch {}
     }
@@ -19851,7 +21027,7 @@ async function applyPreparedUpdatesAtomically(preparedUpdates, options2) {
       }
       if (existsSync18(appliedWrite.backupPath)) {
         try {
-          await rm7(appliedWrite.backupPath, { force: true });
+          await rm8(appliedWrite.backupPath, { force: true });
         } catch (error) {
           if (!options2.quiet) {
             const errorMessage = error instanceof Error ? error.message : String(error);
@@ -19864,9 +21040,9 @@ async function applyPreparedUpdatesAtomically(preparedUpdates, options2) {
   try {
     for (const prepared of preparedUpdates) {
       for (const preparedFile of prepared.preparedFiles) {
-        const targetDir = dirname7(preparedFile.targetPath);
+        const targetDir = dirname8(preparedFile.targetPath);
         if (!existsSync18(targetDir)) {
-          await mkdir9(targetDir, { recursive: true });
+          await mkdir10(targetDir, { recursive: true });
         }
         if (existsSync18(preparedFile.targetPath)) {
           const currentTargetStats = await stat4(preparedFile.targetPath);
@@ -19874,12 +21050,12 @@ async function applyPreparedUpdatesAtomically(preparedUpdates, options2) {
             throw new ValidationError(`Cannot update "${preparedFile.resolvedTarget}": target path is a directory.`);
           }
         }
-        const tempPath = `${preparedFile.targetPath}.ocx-update-tmp-${randomUUID2()}`;
+        const tempPath = `${preparedFile.targetPath}.ocx-update-tmp-${randomUUID3()}`;
         await writeFile5(tempPath, preparedFile.content);
         tempPaths.add(tempPath);
         let backupPath = null;
         if (existsSync18(preparedFile.targetPath)) {
-          backupPath = `${preparedFile.targetPath}.ocx-update-backup-${randomUUID2()}`;
+          backupPath = `${preparedFile.targetPath}.ocx-update-backup-${randomUUID3()}`;
           await renameFile(preparedFile.targetPath, backupPath);
           appliedWrites.push({
             targetPath: preparedFile.targetPath,
@@ -19950,7 +21126,7 @@ Please use a fully qualified name (alias/component).`);
     });
     if (matchingIds.length === 0) {
       throw new NotFoundError(`Component '${name}' is not installed.
-Run 'ocx add ${name}' to install it first.`);
+Run '${formatAddCommandHint(name, options2)}' to install it first.`);
     }
     const canonicalId = matchingIds[0];
     if (!canonicalId) {
@@ -19977,6 +21153,92 @@ function outputUpdateDryRun(results, options2) {
   outputDryRun(dryRunResult, { json: options2.json, quiet: options2.quiet });
 }
 
+// src/commands/validate.ts
+import { resolve as resolve7 } from "path";
+init_errors2();
+function createLoadValidationError2(message, errorKind) {
+  if (errorKind === "not_found") {
+    return new NotFoundError(message);
+  }
+  if (errorKind === "parse_error") {
+    return new OCXError(message, "CONFIG_ERROR", EXIT_CODES.CONFIG);
+  }
+  return new OCXError(message, "CONFIG_ERROR", EXIT_CODES.CONFIG);
+}
+function createValidationFailureError2(errors3, failureType) {
+  const summary = summarizeValidationErrors(errors3, {
+    schemaErrors: failureType === "schema" ? errors3.length : 0
+  });
+  const details = {
+    valid: false,
+    errors: errors3,
+    summary: {
+      valid: false,
+      totalErrors: summary.totalErrors,
+      schemaErrors: summary.schemaErrors,
+      sourceFileErrors: summary.sourceFileErrors,
+      circularDependencyErrors: summary.circularDependencyErrors,
+      duplicateTargetErrors: summary.duplicateTargetErrors,
+      otherErrors: summary.otherErrors
+    }
+  };
+  return new ValidationFailedError(details);
+}
+function outputValidationErrors(errors3) {
+  for (const error of errors3) {
+    console.log(kleur_default.red(`  ${error}`));
+  }
+}
+function registerValidateCommand(program2) {
+  program2.command("validate").description("Validate a registry source (for registry authors)").argument("[path]", "Registry source directory", ".").option("--cwd <path>", "Working directory", process.cwd()).option("--json", "Output as JSON", false).option("-q, --quiet", "Suppress output", false).option("--no-duplicate-targets", "Skip duplicate target validation").action(async (path9, options2) => {
+    try {
+      const sourcePath = resolve7(options2.cwd, path9);
+      const validationResult = await runCompleteValidation(sourcePath, {
+        skipDuplicateTargets: options2.duplicateTargets === false
+      });
+      if (!validationResult.success) {
+        const [firstError = "Registry validation failed"] = validationResult.errors;
+        if (validationResult.failureType === "load") {
+          const loadError = createLoadValidationError2(firstError, validationResult.loadErrorKind);
+          if (!options2.json && options2.quiet) {
+            const exitCode = loadError instanceof OCXError ? loadError.exitCode : EXIT_CODES.GENERAL;
+            process.exit(exitCode);
+          }
+          throw loadError;
+        }
+        const validationError = createValidationFailureError2(validationResult.errors, validationResult.failureType === "schema" ? "schema" : "rules");
+        if (options2.json) {
+          throw validationError;
+        }
+        if (!options2.quiet) {
+          logger.error(validationError.message);
+          outputValidationErrors(validationResult.errors);
+        }
+        process.exit(validationError.exitCode);
+      }
+      if (!options2.quiet && !options2.json) {
+        logger.success("\u2713 Registry source is valid");
+      }
+      if (options2.json) {
+        outputJson({
+          success: true,
+          data: {
+            valid: true,
+            errors: [],
+            summary: summarizeValidationErrors([])
+          }
+        });
+      }
+    } catch (error) {
+      if (!options2.json && options2.quiet) {
+        const exitCode = error instanceof OCXError ? error.exitCode : EXIT_CODES.GENERAL;
+        process.exit(exitCode);
+      }
+      handleError(error, { json: options2.json });
+    }
+  });
+}
+
 // src/commands/verify.ts
 init_errors2();
 function registerVerifyCommand(program2) {
@@ -20093,7 +21355,7 @@ function registerUpdateCheckHook(program2) {
       return;
     }
     const actionOptions = actionCommand.opts();
-    if (actionOptions.json) {
+    if (actionOptions.json || actionOptions.quiet) {
       return;
     }
     if (!shouldCheckForUpdate())
@@ -20107,7 +21369,7 @@ function registerUpdateCheckHook(program2) {
   });
 }
 // src/index.ts
-var version = "2.0.0";
+var version = "2.0.1";
 async function main2() {
   const program2 = new Command().name("ocx").description("OpenCode Extensions - Install agents, skills, plugins, and commands").version(version);
   registerInitCommand(program2);
@@ -20116,6 +21378,7 @@ async function main2() {
   registerSearchCommand(program2);
   registerRegistryCommand(program2);
   registerBuildCommand(program2);
+  registerValidateCommand(program2);
   registerSelfCommand(program2);
   registerVerifyCommand(program2);
   registerRemoveCommand(program2);
@@ -20140,4 +21403,4 @@ export {
   buildRegistry
 };
 
-//# debugId=851007C87A251D3864756E2164756E21
+//# debugId=4F8B9C341AC7574B64756E2164756E21