@fractary/codex-cli 0.2.2

package/dist/cli.js

@@ -0,0 +1,2246 @@
+#!/usr/bin/env node
+import * as path3 from 'path';
+import 'url';
+import * as fs from 'fs/promises';
+import * as yaml from 'js-yaml';
+import { ValidationError, PermissionDeniedError, ConfigurationError, CodexError } from '@fractary/codex';
+import { Command } from 'commander';
+import chalk6 from 'chalk';
+import { execSync } from 'child_process';
+
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var init_esm_shims = __esm({
+  "../node_modules/tsup/assets/esm_shims.js"() {
+  }
+});
+
+// src/config/migrate-config.ts
+var migrate_config_exports = {};
+__export(migrate_config_exports, {
+  getDefaultYamlConfig: () => getDefaultYamlConfig,
+  isLegacyConfig: () => isLegacyConfig,
+  migrateConfig: () => migrateConfig,
+  readYamlConfig: () => readYamlConfig,
+  writeYamlConfig: () => writeYamlConfig
+});
+async function isLegacyConfig(configPath) {
+  try {
+    const content = await fs.readFile(configPath, "utf-8");
+    const config = JSON.parse(content);
+    return config.version === "3.0" || config.organizationSlug !== void 0 || config.directories !== void 0 || config.rules !== void 0;
+  } catch {
+    return false;
+  }
+}
+async function migrateConfig(legacyConfigPath, options) {
+  const warnings = [];
+  try {
+    const content = await fs.readFile(legacyConfigPath, "utf-8");
+    const legacy = JSON.parse(content);
+    let backupPath;
+    if (options?.createBackup !== false) {
+      const suffix = options?.backupSuffix || (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
+      backupPath = `${legacyConfigPath}.backup-${suffix}`;
+      await fs.writeFile(backupPath, content, "utf-8");
+    }
+    const yamlConfig = {
+      organization: legacy.organization || legacy.organizationSlug || "default"
+    };
+    if (legacy.cache) {
+      yamlConfig.cacheDir = legacy.cache.directory || ".codex-cache";
+    }
+    if (legacy.storage?.providers) {
+      yamlConfig.storage = [];
+      for (const [type, config] of Object.entries(legacy.storage.providers)) {
+        if (type === "github") {
+          const githubConfig = config;
+          yamlConfig.storage.push({
+            type: "github",
+            token: githubConfig.token || "${GITHUB_TOKEN}",
+            apiBaseUrl: githubConfig.baseUrl || "https://api.github.com",
+            branch: githubConfig.branch || "main",
+            priority: 50
+          });
+        } else if (type === "http") {
+          const httpConfig = config;
+          yamlConfig.storage.push({
+            type: "http",
+            baseUrl: httpConfig.baseUrl,
+            headers: httpConfig.headers,
+            timeout: httpConfig.timeout || 3e4,
+            priority: 100
+          });
+        } else if (type === "local") {
+          const localConfig = config;
+          yamlConfig.storage.push({
+            type: "local",
+            basePath: localConfig.basePath || "./knowledge",
+            followSymlinks: localConfig.followSymlinks || false,
+            priority: 10
+          });
+        } else {
+          warnings.push(`Unknown storage provider type: ${type}`);
+        }
+      }
+      if (yamlConfig.storage.length === 0) {
+        yamlConfig.storage.push({
+          type: "github",
+          token: "${GITHUB_TOKEN}",
+          apiBaseUrl: "https://api.github.com",
+          branch: "main",
+          priority: 50
+        });
+        warnings.push("No storage providers found, added default GitHub provider");
+      }
+    }
+    if (legacy.types?.custom && Array.isArray(legacy.types.custom)) {
+      yamlConfig.types = {
+        custom: {}
+      };
+      for (const customType of legacy.types.custom) {
+        if (customType.name) {
+          yamlConfig.types.custom[customType.name] = {
+            description: customType.description,
+            patterns: customType.patterns || [],
+            defaultTtl: customType.defaultTtl,
+            archiveAfterDays: customType.archiveAfterDays,
+            archiveStorage: customType.archiveStorage
+          };
+        }
+      }
+    }
+    if (legacy.sync) {
+      yamlConfig.sync = {
+        bidirectional: true,
+        conflictResolution: "prompt",
+        exclude: [
+          "node_modules/**",
+          ".git/**",
+          "**/*.log",
+          ".env"
+        ]
+      };
+      if (legacy.sync.environments) {
+        warnings.push("Sync environments are not directly supported in v3.0 - please configure sync rules manually");
+      }
+    }
+    if (legacy.mcp) {
+      yamlConfig.mcp = {
+        enabled: legacy.mcp.enabled || false,
+        port: legacy.mcp.port || 3e3
+      };
+    }
+    return {
+      success: true,
+      yamlConfig,
+      warnings,
+      backupPath
+    };
+  } catch (error) {
+    throw new Error(
+      `Migration failed: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+}
+async function writeYamlConfig(config, outputPath) {
+  const dir = path3.dirname(outputPath);
+  await fs.mkdir(dir, { recursive: true });
+  const yamlContent = yaml.dump(config, {
+    indent: 2,
+    lineWidth: 80,
+    noRefs: true,
+    sortKeys: false
+  });
+  await fs.writeFile(outputPath, yamlContent, "utf-8");
+}
+function getDefaultYamlConfig(organization) {
+  return {
+    organization,
+    cacheDir: ".codex-cache",
+    storage: [
+      {
+        type: "local",
+        basePath: "./knowledge",
+        followSymlinks: false,
+        priority: 10
+      },
+      {
+        type: "github",
+        token: "${GITHUB_TOKEN}",
+        apiBaseUrl: "https://api.github.com",
+        branch: "main",
+        priority: 50
+      },
+      {
+        type: "http",
+        baseUrl: "https://codex.example.com",
+        timeout: 3e4,
+        priority: 100
+      }
+    ],
+    types: {
+      custom: {}
+    },
+    permissions: {
+      default: "read",
+      rules: [
+        {
+          pattern: "internal/**",
+          permission: "none"
+        },
+        {
+          pattern: "public/**",
+          permission: "read"
+        }
+      ]
+    },
+    sync: {
+      bidirectional: true,
+      conflictResolution: "prompt",
+      exclude: [
+        "node_modules/**",
+        ".git/**",
+        "**/*.log",
+        ".env"
+      ]
+    },
+    mcp: {
+      enabled: false,
+      port: 3e3
+    }
+  };
+}
+async function readYamlConfig(configPath) {
+  const content = await fs.readFile(configPath, "utf-8");
+  const config = yaml.load(content);
+  if (!config.organization) {
+    throw new Error("Invalid config: organization is required");
+  }
+  return config;
+}
+var init_migrate_config = __esm({
+  "src/config/migrate-config.ts"() {
+    init_esm_shims();
+  }
+});
+
+// src/config/config-types.ts
+var config_types_exports = {};
+__export(config_types_exports, {
+  parseDuration: () => parseDuration,
+  parseSize: () => parseSize,
+  resolveEnvVars: () => resolveEnvVars,
+  resolveEnvVarsInConfig: () => resolveEnvVarsInConfig
+});
+function parseDuration(duration) {
+  if (typeof duration === "number") {
+    return duration;
+  }
+  const match = duration.match(/^(\d+)([smhdwMy])$/);
+  if (!match) {
+    throw new Error(`Invalid duration format: ${duration}`);
+  }
+  const [, valueStr, unit] = match;
+  const value = parseInt(valueStr, 10);
+  switch (unit) {
+    case "s":
+      return value;
+    case "m":
+      return value * 60;
+    case "h":
+      return value * 3600;
+    case "d":
+      return value * 86400;
+    case "w":
+      return value * 604800;
+    case "M":
+      return value * 2592e3;
+    // 30 days
+    case "y":
+      return value * 31536e3;
+    // 365 days
+    default:
+      throw new Error(`Unknown duration unit: ${unit}`);
+  }
+}
+function parseSize(size) {
+  if (typeof size === "number") {
+    return size;
+  }
+  const match = size.match(/^(\d+(?:\.\d+)?)\s*(B|KB|MB|GB)$/i);
+  if (!match) {
+    throw new Error(`Invalid size format: ${size}`);
+  }
+  const [, valueStr, unit] = match;
+  const value = parseFloat(valueStr);
+  switch (unit.toUpperCase()) {
+    case "B":
+      return value;
+    case "KB":
+      return value * 1024;
+    case "MB":
+      return value * 1024 * 1024;
+    case "GB":
+      return value * 1024 * 1024 * 1024;
+    default:
+      throw new Error(`Unknown size unit: ${unit}`);
+  }
+}
+function resolveEnvVars(value) {
+  return value.replace(/\$\{([^}]+)\}/g, (_, varName) => {
+    const envValue = process.env[varName];
+    if (envValue === void 0) {
+      console.warn(`Warning: Environment variable ${varName} is not set`);
+      return `\${${varName}}`;
+    }
+    return envValue;
+  });
+}
+function resolveEnvVarsInConfig(config) {
+  if (typeof config === "string") {
+    return resolveEnvVars(config);
+  }
+  if (Array.isArray(config)) {
+    return config.map((item) => resolveEnvVarsInConfig(item));
+  }
+  if (config !== null && typeof config === "object") {
+    const result = {};
+    for (const [key, value] of Object.entries(config)) {
+      result[key] = resolveEnvVarsInConfig(value);
+    }
+    return result;
+  }
+  return config;
+}
+var init_config_types = __esm({
+  "src/config/config-types.ts"() {
+    init_esm_shims();
+  }
+});
+
+// src/client/codex-client.ts
+var codex_client_exports = {};
+__export(codex_client_exports, {
+  CodexClient: () => CodexClient,
+  CodexError: () => CodexError,
+  ConfigurationError: () => ConfigurationError,
+  PermissionDeniedError: () => PermissionDeniedError,
+  ValidationError: () => ValidationError
+});
+var CodexClient;
+var init_codex_client = __esm({
+  "src/client/codex-client.ts"() {
+    init_esm_shims();
+    CodexClient = class _CodexClient {
+      cache;
+      storage;
+      types;
+      organization;
+      /**
+       * Private constructor - use CodexClient.create() instead
+       */
+      constructor(cache, storage, types, organization) {
+        this.cache = cache;
+        this.storage = storage;
+        this.types = types;
+        this.organization = organization;
+      }
+      /**
+       * Create a new CodexClient instance
+       *
+       * @param options - Optional configuration
+       * @returns Promise resolving to CodexClient instance
+       *
+       * @example
+       * ```typescript
+       * const client = await CodexClient.create();
+       * ```
+       */
+      static async create(options) {
+        const {
+          CacheManager,
+          createStorageManager,
+          createDefaultRegistry,
+          CodexError: CodexError2,
+          ConfigurationError: ConfigurationError2
+        } = await import('@fractary/codex');
+        const { readYamlConfig: readYamlConfig2 } = await Promise.resolve().then(() => (init_migrate_config(), migrate_config_exports));
+        const { resolveEnvVarsInConfig: resolveEnvVarsInConfig2 } = await Promise.resolve().then(() => (init_config_types(), config_types_exports));
+        try {
+          const configPath = path3.join(process.cwd(), ".fractary", "codex.yaml");
+          let config;
+          try {
+            config = await readYamlConfig2(configPath);
+            config = resolveEnvVarsInConfig2(config);
+          } catch (error) {
+            throw new ConfigurationError2(
+              `Failed to load configuration from ${configPath}. Run "fractary codex init" to create a configuration.`
+            );
+          }
+          const organization = options?.organizationSlug || config.organization;
+          const cacheDir = options?.cacheDir || config.cacheDir || ".codex-cache";
+          const storageConfig = {};
+          if (config.storage && Array.isArray(config.storage)) {
+            for (const provider of config.storage) {
+              if (provider.type === "github") {
+                storageConfig.github = {
+                  token: provider.token || process.env.GITHUB_TOKEN,
+                  apiBaseUrl: provider.apiBaseUrl || "https://api.github.com",
+                  branch: provider.branch || "main"
+                };
+              } else if (provider.type === "http") {
+                storageConfig.http = {
+                  baseUrl: provider.baseUrl,
+                  headers: provider.headers,
+                  timeout: provider.timeout || 3e4
+                };
+              } else if (provider.type === "local") {
+                storageConfig.local = {
+                  basePath: provider.basePath || "./knowledge",
+                  followSymlinks: provider.followSymlinks || false
+                };
+              }
+            }
+          }
+          const storage = createStorageManager(storageConfig);
+          const cache = new CacheManager({
+            cacheDir,
+            defaultTtl: 86400,
+            // 24 hours
+            maxMemoryEntries: 100,
+            maxMemorySize: 50 * 1024 * 1024,
+            // 50MB
+            enablePersistence: true
+          });
+          cache.setStorageManager(storage);
+          const types = createDefaultRegistry();
+          if (config.types?.custom) {
+            for (const [name, customType] of Object.entries(config.types.custom)) {
+              const ct = customType;
+              types.register({
+                name,
+                description: ct.description || `Custom type: ${name}`,
+                patterns: ct.patterns || [],
+                defaultTtl: ct.defaultTtl || 86400,
+                archiveAfterDays: ct.archiveAfterDays !== void 0 ? ct.archiveAfterDays : null,
+                archiveStorage: ct.archiveStorage || null
+              });
+            }
+          }
+          return new _CodexClient(cache, storage, types, organization);
+        } catch (error) {
+          if (error instanceof CodexError2) {
+            throw error;
+          }
+          throw new CodexError2(
+            `Failed to initialize CodexClient: ${error instanceof Error ? error.message : String(error)}`
+          );
+        }
+      }
+      /**
+       * Fetch a document by codex:// URI
+       *
+       * This method:
+       * 1. Validates the URI format
+       * 2. Resolves the URI to a reference
+       * 3. Uses CacheManager.get() which handles cache-first fetch
+       *
+       * @param uri - Codex URI (e.g., codex://org/project/path/to/file.md)
+       * @param options - Fetch options
+       * @returns Promise resolving to fetch result
+       *
+       * @throws {CodexError} If URI format is invalid or fetch fails
+       *
+       * @example
+       * ```typescript
+       * const result = await client.fetch('codex://fractary/codex/docs/README.md');
+       * console.log(result.content.toString());
+       * ```
+       */
+      async fetch(uri, options) {
+        const { validateUri, resolveReference, CodexError: CodexError2 } = await import('@fractary/codex');
+        if (!validateUri(uri)) {
+          throw new CodexError2(`Invalid codex URI: ${uri}`);
+        }
+        const resolved = resolveReference(uri);
+        if (!resolved) {
+          throw new CodexError2(`Failed to resolve URI: ${uri}`);
+        }
+        try {
+          if (options?.bypassCache) {
+            const result2 = await this.storage.fetch(resolved);
+            return {
+              content: result2.content,
+              fromCache: false,
+              metadata: {
+                fetchedAt: (/* @__PURE__ */ new Date()).toISOString(),
+                contentLength: result2.size
+              }
+            };
+          }
+          const result = await this.cache.get(resolved, {
+            ttl: options?.ttl
+          });
+          return {
+            content: result.content,
+            fromCache: true,
+            // CacheManager.get handles cache logic
+            metadata: {
+              contentLength: result.size
+            }
+          };
+        } catch (error) {
+          throw new CodexError2(
+            `Failed to fetch ${uri}: ${error instanceof Error ? error.message : String(error)}`
+          );
+        }
+      }
+      /**
+       * Invalidate cache entries
+       *
+       * @param pattern - Optional glob pattern to match entries
+       *                  If not provided, clears all entries
+       *
+       * @example
+       * ```typescript
+       * // Clear all cache
+       * await client.invalidateCache();
+       *
+       * // Clear specific URI
+       * await client.invalidateCache('codex://fractary/codex/docs/README.md');
+       * ```
+       */
+      async invalidateCache(pattern) {
+        if (pattern) {
+          await this.cache.invalidate(pattern);
+        } else {
+          await this.cache.clear();
+        }
+      }
+      /**
+       * Get cache statistics
+       *
+       * @returns Promise resolving to cache stats
+       *
+       * @example
+       * ```typescript
+       * const stats = await client.getCacheStats();
+       * console.log(`Cache entries: ${stats.totalEntries}`);
+       * console.log(`Total size: ${stats.totalSize}`);
+       * ```
+       */
+      async getCacheStats() {
+        return this.cache.getStats();
+      }
+      /**
+       * Get the type registry
+       *
+       * Provides access to built-in and custom artifact types
+       *
+       * @returns TypeRegistry instance
+       *
+       * @example
+       * ```typescript
+       * const registry = client.getTypeRegistry();
+       * const types = registry.list();
+       * ```
+       */
+      getTypeRegistry() {
+        return this.types;
+      }
+      /**
+       * Get the cache manager (for advanced operations)
+       *
+       * @returns CacheManager instance
+       */
+      getCacheManager() {
+        return this.cache;
+      }
+      /**
+       * Get the storage manager (for advanced operations)
+       *
+       * @returns StorageManager instance
+       */
+      getStorageManager() {
+        return this.storage;
+      }
+      /**
+       * Get the organization slug
+       *
+       * @returns Organization slug string
+       */
+      getOrganization() {
+        return this.organization;
+      }
+    };
+  }
+});
+
+// src/cli.ts
+init_esm_shims();
+
+// src/commands/init.ts
+init_esm_shims();
+init_migrate_config();
+async function getOrgFromGitRemote() {
+  try {
+    const { execSync: execSync2 } = __require("child_process");
+    const remote = execSync2("git remote get-url origin 2>/dev/null", { encoding: "utf-8" }).trim();
+    const sshMatch = remote.match(/git@github\.com:([^/]+)\//);
+    const httpsMatch = remote.match(/github\.com\/([^/]+)\//);
+    return sshMatch?.[1] || httpsMatch?.[1] || null;
+  } catch {
+    return null;
+  }
+}
+async function fileExists(filePath) {
+  try {
+    await fs.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function initCommand() {
+  const cmd = new Command("init");
+  cmd.description("Initialize Codex v3.0 with YAML configuration").option("--org <slug>", 'Organization slug (e.g., "fractary")').option("--mcp", "Enable MCP server registration").option("--force", "Overwrite existing configuration").action(async (options) => {
+    try {
+      console.log(chalk6.blue("Initializing Codex v3.0 (YAML format)...\n"));
+      let org = options.org;
+      if (!org) {
+        org = await getOrgFromGitRemote();
+      }
+      if (!org) {
+        try {
+          const { resolveOrganization } = await import('@fractary/codex');
+          org = resolveOrganization({
+            repoName: path3.basename(process.cwd())
+          });
+        } catch {
+        }
+      }
+      if (!org) {
+        org = path3.basename(process.cwd()).split("-")[0] || "default";
+        console.log(chalk6.yellow(`\u26A0 Could not detect organization, using: ${org}`));
+        console.log(chalk6.dim("  Use --org <slug> to specify explicitly\n"));
+      } else {
+        console.log(chalk6.dim(`Organization: ${chalk6.cyan(org)}
+`));
+      }
+      const configDir = path3.join(process.cwd(), ".fractary");
+      const configPath = path3.join(configDir, "codex.yaml");
+      const configExists = await fileExists(configPath);
+      const legacyConfigPath = path3.join(process.cwd(), ".fractary", "plugins", "codex", "config.json");
+      const legacyExists = await fileExists(legacyConfigPath);
+      if (configExists && !options.force) {
+        console.log(chalk6.yellow("\u26A0 Configuration already exists at .fractary/codex.yaml"));
+        console.log(chalk6.dim("Use --force to overwrite"));
+        process.exit(1);
+      }
+      if (legacyExists && !configExists) {
+        console.log(chalk6.yellow("\u26A0 Legacy configuration detected at .fractary/plugins/codex/config.json"));
+        console.log(chalk6.dim('Run "fractary codex migrate" to upgrade to YAML format\n'));
+      }
+      console.log("Creating directory structure...");
+      const dirs = [
+        ".fractary",
+        ".codex-cache"
+      ];
+      for (const dir of dirs) {
+        await fs.mkdir(path3.join(process.cwd(), dir), { recursive: true });
+        console.log(chalk6.green("\u2713"), chalk6.dim(dir + "/"));
+      }
+      console.log("\nCreating YAML configuration...");
+      const config = getDefaultYamlConfig(org);
+      if (options.mcp && config.mcp) {
+        config.mcp.enabled = true;
+      }
+      await writeYamlConfig(config, configPath);
+      console.log(chalk6.green("\u2713"), chalk6.dim(".fractary/codex.yaml"));
+      console.log(chalk6.green("\n\u2713 Codex v3.0 initialized successfully!\n"));
+      console.log(chalk6.bold("Configuration:"));
+      console.log(chalk6.dim(`  Organization: ${org}`));
+      console.log(chalk6.dim(`  Cache: .codex-cache/`));
+      console.log(chalk6.dim(`  Config: .fractary/codex.yaml`));
+      if (options.mcp) {
+        console.log(chalk6.dim(`  MCP Server: Enabled (port 3000)`));
+      }
+      console.log(chalk6.bold("\nStorage providers configured:"));
+      console.log(chalk6.dim("  - Local filesystem (./knowledge)"));
+      console.log(chalk6.dim("  - GitHub (requires GITHUB_TOKEN)"));
+      console.log(chalk6.dim("  - HTTP endpoint"));
+      console.log(chalk6.bold("\nNext steps:"));
+      console.log(chalk6.dim('  1. Set your GitHub token: export GITHUB_TOKEN="your_token"'));
+      console.log(chalk6.dim("  2. Edit .fractary/codex.yaml to configure storage providers"));
+      console.log(chalk6.dim("  3. Fetch a document: fractary codex fetch codex://org/project/path"));
+      console.log(chalk6.dim("  4. Check cache: fractary codex cache list"));
+      if (legacyExists) {
+        console.log(chalk6.yellow("\n\u26A0 Legacy config detected:"));
+        console.log(chalk6.dim('  Run "fractary codex migrate" to convert your existing config'));
+      }
+    } catch (error) {
+      console.error(chalk6.red("Error:"), error.message);
+      process.exit(1);
+    }
+  });
+  return cmd;
+}
+
+// src/commands/fetch.ts
+init_esm_shims();
+
+// src/client/get-client.ts
+init_esm_shims();
+var clientInstance = null;
+async function getClient(options) {
+  if (!clientInstance) {
+    const { CodexClient: CodexClient2 } = await Promise.resolve().then(() => (init_codex_client(), codex_client_exports));
+    clientInstance = await CodexClient2.create(options);
+  }
+  return clientInstance;
+}
+
+// src/commands/fetch.ts
+function hashContent(content) {
+  const crypto = __require("crypto");
+  return crypto.createHash("sha256").update(content).digest("hex").slice(0, 16);
+}
+function fetchCommand() {
+  const cmd = new Command("fetch");
+  cmd.description("Fetch a document by codex:// URI reference").argument("<uri>", "Codex URI (e.g., codex://org/project/docs/file.md)").option("--bypass-cache", "Skip cache and fetch directly from source").option("--ttl <seconds>", "Override default TTL (in seconds)", parseInt).option("--json", "Output as JSON with metadata").option("--output <file>", "Write content to file instead of stdout").action(async (uri, options) => {
+    try {
+      const { validateUri } = await import('@fractary/codex');
+      if (!validateUri(uri)) {
+        console.error(chalk6.red("Error: Invalid URI format"));
+        console.log(chalk6.dim("Expected: codex://org/project/path/to/file.md"));
+        console.log(chalk6.dim("Example: codex://fractary/codex/docs/api.md"));
+        process.exit(1);
+      }
+      const client = await getClient();
+      if (!options.json && !options.bypassCache) {
+        console.error(chalk6.dim(`Fetching ${uri}...`));
+      }
+      const result = await client.fetch(uri, {
+        bypassCache: options.bypassCache,
+        ttl: options.ttl
+      });
+      if (options.json) {
+        const output = {
+          uri,
+          content: result.content.toString("utf-8"),
+          metadata: {
+            fromCache: result.fromCache,
+            fetchedAt: result.metadata?.fetchedAt,
+            expiresAt: result.metadata?.expiresAt,
+            contentLength: result.metadata?.contentLength || result.content.length,
+            contentHash: hashContent(result.content)
+          }
+        };
+        console.log(JSON.stringify(output, null, 2));
+      } else if (options.output) {
+        await fs.writeFile(options.output, result.content);
+        console.log(chalk6.green("\u2713"), `Written to ${options.output}`);
+        console.log(chalk6.dim(`  Size: ${result.content.length} bytes`));
+        if (result.fromCache) {
+          console.log(chalk6.dim("  Source: cache"));
+        } else {
+          console.log(chalk6.dim("  Source: storage"));
+        }
+      } else {
+        if (result.fromCache && !options.bypassCache) {
+          console.error(chalk6.green("\u2713"), chalk6.dim("from cache\n"));
+        } else {
+          console.error(chalk6.green("\u2713"), chalk6.dim("fetched\n"));
+        }
+        console.log(result.content.toString("utf-8"));
+      }
+    } catch (error) {
+      console.error(chalk6.red("Error:"), error.message);
+      if (error.message.includes("Failed to load configuration")) {
+        console.log(chalk6.dim('\nRun "fractary codex init" to create a configuration.'));
+      } else if (error.message.includes("GITHUB_TOKEN")) {
+        console.log(chalk6.dim('\nSet your GitHub token: export GITHUB_TOKEN="your_token"'));
+      } else if (error.message.includes("not found") || error.message.includes("404")) {
+        console.log(chalk6.dim("\nThe document may not exist or you may not have access."));
+        console.log(chalk6.dim("Check the URI and ensure your storage providers are configured correctly."));
+      }
+      process.exit(1);
+    }
+  });
+  return cmd;
+}
+
+// src/commands/cache/index.ts
+init_esm_shims();
+
+// src/commands/cache/list.ts
+init_esm_shims();
+function formatSize(bytes) {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+function cacheListCommand() {
+  const cmd = new Command("list");
+  cmd.description("List cache information").option("--json", "Output as JSON").action(async (options) => {
+    try {
+      const client = await getClient();
+      const stats = await client.getCacheStats();
+      if (stats.entryCount === 0) {
+        if (options.json) {
+          console.log(JSON.stringify({ entries: 0, message: "Cache is empty" }));
+        } else {
+          console.log(chalk6.yellow("Cache is empty."));
+          console.log(chalk6.dim("Fetch some documents to populate the cache."));
+        }
+        return;
+      }
+      if (options.json) {
+        console.log(JSON.stringify({
+          entryCount: stats.entryCount,
+          totalSize: stats.totalSize,
+          freshCount: stats.freshCount,
+          staleCount: stats.staleCount,
+          expiredCount: stats.expiredCount
+        }, null, 2));
+        return;
+      }
+      console.log(chalk6.bold("Cache Overview\n"));
+      console.log(chalk6.bold("Entries:"));
+      console.log(`  Total:    ${chalk6.cyan(stats.entryCount.toString())} entries`);
+      console.log(`  Fresh:    ${chalk6.green(stats.freshCount.toString())} entries`);
+      console.log(`  Stale:    ${stats.staleCount > 0 ? chalk6.yellow(stats.staleCount.toString()) : chalk6.dim("0")} entries`);
+      console.log(`  Expired:  ${stats.expiredCount > 0 ? chalk6.red(stats.expiredCount.toString()) : chalk6.dim("0")} entries`);
+      console.log("");
+      console.log(chalk6.bold("Storage:"));
+      console.log(`  Total size: ${chalk6.cyan(formatSize(stats.totalSize))}`);
+      console.log("");
+      const healthPercent = stats.entryCount > 0 ? stats.freshCount / stats.entryCount * 100 : 100;
+      const healthColor = healthPercent > 80 ? chalk6.green : healthPercent > 50 ? chalk6.yellow : chalk6.red;
+      console.log(`Cache health: ${healthColor(`${healthPercent.toFixed(0)}% fresh`)}`);
+      console.log("");
+      console.log(chalk6.dim("Note: Individual cache entries are managed by the SDK."));
+      console.log(chalk6.dim('Use "fractary codex cache stats" for detailed statistics.'));
+      console.log(chalk6.dim('Use "fractary codex cache clear" to clear cache entries.'));
+    } catch (error) {
+      console.error(chalk6.red("Error:"), error.message);
+      process.exit(1);
+    }
+  });
+  return cmd;
+}
+
+// src/commands/cache/clear.ts
+init_esm_shims();
+function cacheClearCommand() {
+  const cmd = new Command("clear");
+  cmd.description("Clear cache entries").option("--all", "Clear entire cache").option("--pattern <glob>", 'Clear entries matching URI pattern (e.g., "codex://fractary/*")').option("--dry-run", "Show what would be cleared without actually clearing").action(async (options) => {
+    try {
+      const client = await getClient();
+      const statsBefore = await client.getCacheStats();
+      if (statsBefore.entryCount === 0) {
+        console.log(chalk6.yellow("Cache is already empty. Nothing to clear."));
+        return;
+      }
+      let pattern;
+      if (options.all) {
+        pattern = void 0;
+      } else if (options.pattern) {
+        pattern = options.pattern;
+      } else {
+        console.log(chalk6.yellow("Please specify what to clear:"));
+        console.log(chalk6.dim("  --all        Clear entire cache"));
+        console.log(chalk6.dim('  --pattern    Clear entries matching pattern (e.g., "codex://fractary/*")'));
+        console.log("");
+        console.log(chalk6.dim("Examples:"));
+        console.log(chalk6.dim("  fractary codex cache clear --all"));
+        console.log(chalk6.dim('  fractary codex cache clear --pattern "codex://fractary/cli/*"'));
+        return;
+      }
+      if (options.dryRun) {
+        console.log(chalk6.blue("Dry run - would clear:\n"));
+        if (pattern) {
+          console.log(chalk6.dim(`  Pattern: ${pattern}`));
+          console.log(chalk6.dim(`  This would invalidate matching cache entries`));
+        } else {
+          console.log(chalk6.dim(`  All cache entries (${statsBefore.entryCount} entries)`));
+        }
+        console.log(chalk6.dim(`
+Total size: ${formatSize2(statsBefore.totalSize)}`));
+        return;
+      }
+      if (pattern) {
+        console.log(chalk6.blue(`Clearing cache entries matching pattern: ${pattern}
+`));
+        await client.invalidateCache(pattern);
+      } else {
+        console.log(chalk6.blue(`Clearing entire cache (${statsBefore.entryCount} entries)...
+`));
+        await client.invalidateCache();
+      }
+      const statsAfter = await client.getCacheStats();
+      const entriesCleared = statsBefore.entryCount - statsAfter.entryCount;
+      const sizeFreed = statsBefore.totalSize - statsAfter.totalSize;
+      console.log(chalk6.green(`\u2713 Cleared ${entriesCleared} entries (${formatSize2(sizeFreed)} freed)`));
+      if (statsAfter.entryCount > 0) {
+        console.log(chalk6.dim(`  Remaining: ${statsAfter.entryCount} entries (${formatSize2(statsAfter.totalSize)})`));
+      }
+    } catch (error) {
+      console.error(chalk6.red("Error:"), error.message);
+      process.exit(1);
+    }
+  });
+  return cmd;
+}
+function formatSize2(bytes) {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+
+// src/commands/cache/stats.ts
+init_esm_shims();
+function formatSize3(bytes) {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+function cacheStatsCommand() {
+  const cmd = new Command("stats");
+  cmd.description("Display cache statistics").option("--json", "Output as JSON").action(async (options) => {
+    try {
+      const client = await getClient();
+      const stats = await client.getCacheStats();
+      if (options.json) {
+        console.log(JSON.stringify(stats, null, 2));
+        return;
+      }
+      console.log(chalk6.bold("Cache Statistics\n"));
+      console.log(chalk6.bold("Overview"));
+      console.log(`  Total entries:     ${chalk6.cyan(stats.entryCount.toString())}`);
+      console.log(`  Total size:        ${chalk6.cyan(formatSize3(stats.totalSize))}`);
+      console.log(`  Fresh entries:     ${chalk6.green(stats.freshCount.toString())}`);
+      console.log(`  Stale entries:     ${stats.staleCount > 0 ? chalk6.yellow(stats.staleCount.toString()) : chalk6.dim("0")}`);
+      console.log(`  Expired entries:   ${stats.expiredCount > 0 ? chalk6.red(stats.expiredCount.toString()) : chalk6.dim("0")}`);
+      console.log("");
+      const healthPercent = stats.entryCount > 0 ? stats.freshCount / stats.entryCount * 100 : 100;
+      const healthColor = healthPercent > 80 ? chalk6.green : healthPercent > 50 ? chalk6.yellow : chalk6.red;
+      console.log(`Cache health: ${healthColor(`${healthPercent.toFixed(0)}% fresh`)}`);
+      if (stats.expiredCount > 0) {
+        console.log(chalk6.dim('\nRun "fractary codex cache clear --pattern <pattern>" to clean up entries.'));
+      }
+      if (stats.entryCount === 0) {
+        console.log(chalk6.dim("\nNo cached entries. Fetch some documents to populate the cache."));
+      }
+    } catch (error) {
+      console.error(chalk6.red("Error:"), error.message);
+      process.exit(1);
+    }
+  });
+  return cmd;
+}
+
+// src/commands/cache/index.ts
+function cacheCommand() {
+  const cmd = new Command("cache");
+  cmd.description("Manage the codex document cache");
+  cmd.addCommand(cacheListCommand());
+  cmd.addCommand(cacheClearCommand());
+  cmd.addCommand(cacheStatsCommand());
+  return cmd;
+}
+
+// src/commands/sync/index.ts
+init_esm_shims();
+
+// src/commands/sync/project.ts
+init_esm_shims();
+init_migrate_config();
+function getEnvironmentBranch(config, env) {
+  const envMap = config.sync?.environments || {
+    dev: "develop",
+    test: "test",
+    staging: "staging",
+    prod: "main"
+  };
+  return envMap[env] || env;
+}
+function formatBytes(bytes) {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+function formatDuration(ms) {
+  if (ms < 1e3) return `${ms}ms`;
+  return `${(ms / 1e3).toFixed(1)}s`;
+}
+function syncProjectCommand() {
+  const cmd = new Command("project");
+  cmd.description("Sync single project with codex repository").argument("[name]", "Project name (auto-detected if not provided)").option("--env <env>", "Target environment (dev/test/staging/prod)", "prod").option("--dry-run", "Show what would sync without executing").option("--direction <dir>", "Sync direction (to-codex/from-codex/bidirectional)", "bidirectional").option("--include <pattern>", "Include files matching pattern (can be used multiple times)", (val, prev) => prev.concat([val]), []).option("--exclude <pattern>", "Exclude files matching pattern (can be used multiple times)", (val, prev) => prev.concat([val]), []).option("--force", "Force sync without checking timestamps").option("--json", "Output as JSON").action(async (name, options) => {
+    try {
+      const configPath = path3.join(process.cwd(), ".fractary", "codex.yaml");
+      let config;
+      try {
+        config = await readYamlConfig(configPath);
+      } catch (error) {
+        console.error(chalk6.red("Error:"), "Codex not initialized.");
+        console.log(chalk6.dim('Run "fractary codex init" first.'));
+        process.exit(1);
+      }
+      const { createSyncManager, createLocalStorage, detectCurrentProject } = await import('@fractary/codex');
+      let projectName = name;
+      if (!projectName) {
+        const detected = detectCurrentProject();
+        projectName = detected.project || null;
+      }
+      if (!projectName) {
+        console.error(chalk6.red("Error:"), "Could not determine project name.");
+        console.log(chalk6.dim("Provide project name as argument or run from a git repository."));
+        process.exit(1);
+      }
+      const validDirections = ["to-codex", "from-codex", "bidirectional"];
+      if (!validDirections.includes(options.direction)) {
+        console.error(chalk6.red("Error:"), `Invalid direction: ${options.direction}`);
+        console.log(chalk6.dim("Valid options: to-codex, from-codex, bidirectional"));
+        process.exit(1);
+      }
+      const direction = options.direction;
+      const targetBranch = getEnvironmentBranch(config, options.env);
+      const localStorage = createLocalStorage({
+        baseDir: process.cwd()
+      });
+      const syncManager = createSyncManager({
+        localStorage,
+        config: config.sync,
+        manifestPath: path3.join(process.cwd(), ".fractary", ".codex-sync-manifest.json")
+      });
+      const defaultPatterns = config.sync?.include || [
+        "docs/**/*.md",
+        "specs/**/*.md",
+        ".fractary/standards/**",
+        ".fractary/templates/**"
+      ];
+      const includePatterns = options.include.length > 0 ? options.include : defaultPatterns;
+      const excludePatterns = [
+        ...config.sync?.exclude || [],
+        ...options.exclude
+      ];
+      const sourceDir = process.cwd();
+      const allFiles = await syncManager.listLocalFiles(sourceDir);
+      const targetFiles = allFiles.filter((file) => {
+        for (const pattern of excludePatterns) {
+          const regex = new RegExp("^" + pattern.replace(/\*\*/g, ".*").replace(/\*/g, "[^/]*") + "$");
+          if (regex.test(file.path)) {
+            return false;
+          }
+        }
+        for (const pattern of includePatterns) {
+          const regex = new RegExp("^" + pattern.replace(/\*\*/g, ".*").replace(/\*/g, "[^/]*") + "$");
+          if (regex.test(file.path)) {
+            return true;
+          }
+        }
+        return false;
+      });
+      const syncOptions = {
+        direction,
+        dryRun: options.dryRun,
+        force: options.force,
+        include: includePatterns,
+        exclude: excludePatterns
+      };
+      const plan = await syncManager.createPlan(
+        config.organization,
+        projectName,
+        sourceDir,
+        targetFiles,
+        syncOptions
+      );
+      if (plan.totalFiles === 0) {
+        if (options.json) {
+          console.log(JSON.stringify({
+            project: projectName,
+            organization: config.organization,
+            files: [],
+            synced: 0
+          }, null, 2));
+        } else {
+          console.log(chalk6.yellow("No files to sync."));
+        }
+        return;
+      }
+      if (options.json) {
+        const output = {
+          project: projectName,
+          organization: config.organization,
+          environment: options.env,
+          branch: targetBranch,
+          direction,
+          dryRun: options.dryRun || false,
+          plan: {
+            totalFiles: plan.totalFiles,
+            totalBytes: plan.totalBytes,
+            estimatedTime: plan.estimatedTime,
+            conflicts: plan.conflicts.length,
+            skipped: plan.skipped.length
+          },
+          files: plan.files.map((f) => ({
+            path: f.path,
+            operation: f.operation,
+            size: f.size
+          }))
+        };
+        if (options.dryRun) {
+          console.log(JSON.stringify(output, null, 2));
+          return;
+        }
+        const result2 = await syncManager.executePlan(plan, syncOptions);
+        console.log(JSON.stringify({
+          ...output,
+          result: {
+            success: result2.success,
+            synced: result2.synced,
+            failed: result2.failed,
+            skipped: result2.skipped,
+            duration: result2.duration,
+            errors: result2.errors
+          }
+        }, null, 2));
+        return;
+      }
+      console.log(chalk6.bold("Sync Plan\n"));
+      console.log(`  Project:      ${chalk6.cyan(projectName)}`);
+      console.log(`  Organization: ${chalk6.cyan(config.organization)}`);
+      console.log(`  Environment:  ${chalk6.cyan(options.env)} (${targetBranch})`);
+      console.log(`  Direction:    ${chalk6.cyan(direction)}`);
+      console.log(`  Files:        ${chalk6.cyan(plan.totalFiles.toString())}`);
+      console.log(`  Total size:   ${chalk6.cyan(formatBytes(plan.totalBytes))}`);
+      if (plan.estimatedTime) {
+        console.log(`  Est. time:    ${chalk6.dim(formatDuration(plan.estimatedTime))}`);
+      }
+      console.log("");
+      if (plan.conflicts.length > 0) {
+        console.log(chalk6.yellow(`\u26A0 ${plan.conflicts.length} conflicts detected:`));
+        for (const conflict of plan.conflicts.slice(0, 5)) {
+          console.log(chalk6.yellow(`  \u2022 ${conflict.path}`));
+        }
+        if (plan.conflicts.length > 5) {
+          console.log(chalk6.dim(`  ... and ${plan.conflicts.length - 5} more`));
+        }
+        console.log("");
+      }
+      if (plan.skipped.length > 0) {
+        console.log(chalk6.dim(`${plan.skipped.length} files skipped (no changes)`));
+        console.log("");
+      }
+      if (options.dryRun) {
+        console.log(chalk6.blue("Dry run - would sync:\n"));
+        const filesToShow = plan.files.slice(0, 10);
+        for (const file of filesToShow) {
+          const arrow = direction === "to-codex" ? "\u2192" : direction === "from-codex" ? "\u2190" : "\u2194";
+          const opColor = file.operation === "create" ? chalk6.green : file.operation === "update" ? chalk6.yellow : chalk6.dim;
+          console.log(
+            chalk6.dim(`  ${arrow}`),
+            opColor(file.operation.padEnd(7)),
+            file.path,
+            chalk6.dim(`(${formatBytes(file.size || 0)})`)
+          );
+        }
+        if (plan.files.length > 10) {
+          console.log(chalk6.dim(`  ... and ${plan.files.length - 10} more files`));
+        }
+        console.log(chalk6.dim(`
+Total: ${plan.totalFiles} files (${formatBytes(plan.totalBytes)})`));
+        console.log(chalk6.dim("Run without --dry-run to execute sync."));
+        return;
+      }
+      console.log(chalk6.blue("Syncing...\n"));
+      const startTime = Date.now();
+      const result = await syncManager.executePlan(plan, syncOptions);
+      const duration = Date.now() - startTime;
+      console.log("");
+      if (result.success) {
+        console.log(chalk6.green(`\u2713 Sync completed successfully`));
+        console.log(chalk6.dim(`  Synced: ${result.synced} files`));
+        if (result.skipped > 0) {
+          console.log(chalk6.dim(`  Skipped: ${result.skipped} files`));
+        }
+        console.log(chalk6.dim(`  Duration: ${formatDuration(duration)}`));
+      } else {
+        console.log(chalk6.yellow(`\u26A0 Sync completed with errors`));
+        console.log(chalk6.green(`  Synced: ${result.synced} files`));
+        console.log(chalk6.red(`  Failed: ${result.failed} files`));
+        if (result.skipped > 0) {
+          console.log(chalk6.dim(`  Skipped: ${result.skipped} files`));
+        }
+        if (result.errors.length > 0) {
+          console.log("");
+          console.log(chalk6.red("Errors:"));
+          for (const error of result.errors.slice(0, 5)) {
+            console.log(chalk6.red(`  \u2022 ${error.path}: ${error.error}`));
+          }
+          if (result.errors.length > 5) {
+            console.log(chalk6.dim(`  ... and ${result.errors.length - 5} more errors`));
+          }
+        }
+      }
+    } catch (error) {
+      console.error(chalk6.red("Error:"), error.message);
+      process.exit(1);
+    }
+  });
+  return cmd;
+}
+
+// src/commands/sync/org.ts
+init_esm_shims();
+init_migrate_config();
+function getEnvironmentBranch2(config, env) {
+  const envMap = config.sync?.environments || {
+    dev: "develop",
+    test: "test",
+    staging: "staging",
+    prod: "main"
+  };
+  return envMap[env] || env;
+}
+async function discoverRepos(org) {
+  try {
+    const output = execSync(
+      `gh repo list ${org} --json name,url,defaultBranchRef --limit 100`,
+      { encoding: "utf-8", maxBuffer: 10 * 1024 * 1024 }
+    );
+    const repos = JSON.parse(output);
+    return repos.map((repo) => ({
+      name: repo.name,
+      url: repo.url,
+      defaultBranch: repo.defaultBranchRef?.name || "main"
+    }));
+  } catch (error) {
+    throw new Error(`Failed to discover repos: ${error.message}. Ensure GitHub CLI is installed and authenticated.`);
+  }
+}
+function shouldExclude(repoName, excludePatterns) {
+  for (const pattern of excludePatterns) {
+    const regex = new RegExp("^" + pattern.replace(/\*/g, ".*") + "$");
+    if (regex.test(repoName)) {
+      return true;
+    }
+  }
+  return false;
+}
+async function syncRepository(repo, config, direction, syncOptions) {
+  const startTime = Date.now();
+  try {
+    const { createSyncManager, createLocalStorage } = await import('@fractary/codex');
+    const repoDir = path3.join(process.cwd(), "..", repo.name);
+    const localStorage = createLocalStorage({
+      baseDir: repoDir
+    });
+    const syncManager = createSyncManager({
+      localStorage,
+      config: config.sync,
+      manifestPath: path3.join(repoDir, ".fractary", ".codex-sync-manifest.json")
+    });
+    const includePatterns = config.sync?.include || [
+      "docs/**/*.md",
+      "specs/**/*.md",
+      ".fractary/standards/**",
+      ".fractary/templates/**"
+    ];
+    const allFiles = await syncManager.listLocalFiles(repoDir);
+    const targetFiles = allFiles.filter((file) => {
+      for (const pattern of includePatterns) {
+        const regex = new RegExp("^" + pattern.replace(/\*\*/g, ".*").replace(/\*/g, "[^/]*") + "$");
+        if (regex.test(file.path)) {
+          return true;
+        }
+      }
+      return false;
+    });
+    const plan = await syncManager.createPlan(
+      config.organization,
+      repo.name,
+      repoDir,
+      targetFiles,
+      syncOptions
+    );
+    if (plan.totalFiles === 0) {
+      return {
+        repo: repo.name,
+        status: "skipped",
+        filesSynced: 0,
+        duration: Date.now() - startTime
+      };
+    }
+    const result = await syncManager.executePlan(plan, syncOptions);
+    return {
+      repo: repo.name,
+      status: result.success ? "success" : "error",
+      filesSynced: result.synced,
+      duration: Date.now() - startTime,
+      error: result.success ? void 0 : `${result.failed} files failed`
+    };
+  } catch (error) {
+    return {
+      repo: repo.name,
+      status: "error",
+      duration: Date.now() - startTime,
+      error: error.message
+    };
+  }
+}
+function syncOrgCommand() {
+  const cmd = new Command("org");
+  cmd.description("Sync all projects in organization with codex repository").option("--env <env>", "Target environment (dev/test/staging/prod)", "prod").option("--dry-run", "Show what would sync without executing").option("--exclude <pattern>", "Exclude repos matching pattern (can be used multiple times)", (val, prev) => prev.concat([val]), []).option("--parallel <n>", "Number of parallel syncs", parseInt, 3).option("--direction <dir>", "Sync direction (to-codex/from-codex/bidirectional)", "bidirectional").option("--json", "Output as JSON").action(async (options) => {
+    try {
+      const configPath = path3.join(process.cwd(), ".fractary", "codex.yaml");
+      let config;
+      try {
+        config = await readYamlConfig(configPath);
+      } catch (error) {
+        console.error(chalk6.red("Error:"), "Codex not initialized.");
+        console.log(chalk6.dim('Run "fractary codex init" first.'));
+        process.exit(1);
+      }
+      const validDirections = ["to-codex", "from-codex", "bidirectional"];
+      if (!validDirections.includes(options.direction)) {
+        console.error(chalk6.red("Error:"), `Invalid direction: ${options.direction}`);
+        console.log(chalk6.dim("Valid options: to-codex, from-codex, bidirectional"));
+        process.exit(1);
+      }
+      const direction = options.direction;
+      const org = config.organization;
+      const targetBranch = getEnvironmentBranch2(config, options.env);
+      const excludePatterns = [
+        ...config.sync?.exclude || [],
+        ...options.exclude
+      ];
+      if (!options.json) {
+        console.log(chalk6.bold("Organization Sync\n"));
+        console.log(`  Organization: ${chalk6.cyan(org)}`);
+        console.log(`  Environment:  ${chalk6.cyan(options.env)} (${targetBranch})`);
+        console.log(`  Direction:    ${chalk6.cyan(direction)}`);
+        console.log(`  Parallelism:  ${chalk6.cyan(options.parallel.toString())}`);
+        if (excludePatterns.length > 0) {
+          console.log(`  Excluding:    ${chalk6.dim(excludePatterns.join(", "))}`);
+        }
+        console.log("");
+        console.log(chalk6.dim("Discovering repositories..."));
+      }
+      let repos;
+      try {
+        repos = await discoverRepos(org);
+      } catch (error) {
+        if (options.json) {
+          console.log(JSON.stringify({ error: error.message }));
+        } else {
+          console.error(chalk6.red("Error:"), error.message);
+        }
+        process.exit(1);
+      }
+      const eligibleRepos = repos.filter((repo) => !shouldExclude(repo.name, excludePatterns));
+      const excludedRepos = repos.filter((repo) => shouldExclude(repo.name, excludePatterns));
+      if (!options.json) {
+        console.log(chalk6.dim(`Found ${repos.length} repositories (${excludedRepos.length} excluded)
+`));
+      }
+      if (options.dryRun) {
+        if (options.json) {
+          console.log(JSON.stringify({
+            organization: org,
+            environment: options.env,
+            branch: targetBranch,
+            direction,
+            dryRun: true,
+            repos: {
+              total: repos.length,
+              eligible: eligibleRepos.map((r) => r.name),
+              excluded: excludedRepos.map((r) => r.name)
+            }
+          }, null, 2));
+        } else {
+          console.log(chalk6.blue("Dry run - would sync:\n"));
+          for (const repo of eligibleRepos) {
+            console.log(chalk6.green("  \u2713"), repo.name);
+          }
+          if (excludedRepos.length > 0) {
+            console.log("");
+            console.log(chalk6.dim("Excluded:"));
+            for (const repo of excludedRepos) {
+              console.log(chalk6.dim(`  - ${repo.name}`));
+            }
+          }
+          console.log(chalk6.dim(`
+Total: ${eligibleRepos.length} repos would be synced`));
+          console.log(chalk6.dim("Run without --dry-run to execute sync."));
+        }
+        return;
+      }
+      if (!options.json) {
+        console.log(chalk6.blue("Syncing repositories...\n"));
+      }
+      const results = [];
+      const syncOptions = {
+        direction,
+        dryRun: false,
+        force: false
+      };
+      for (let i = 0; i < eligibleRepos.length; i += options.parallel) {
+        const batch = eligibleRepos.slice(i, i + options.parallel);
+        const batchResults = await Promise.all(
+          batch.map((repo) => syncRepository(repo, config, direction, syncOptions))
+        );
+        for (const result of batchResults) {
+          results.push(result);
+          if (!options.json) {
+            if (result.status === "success") {
+              console.log(
+                chalk6.green("  \u2713"),
+                result.repo,
+                chalk6.dim(`(${result.filesSynced} files in ${result.duration}ms)`)
+              );
+            } else if (result.status === "skipped") {
+              console.log(
+                chalk6.dim("  -"),
+                result.repo,
+                chalk6.dim("(no files to sync)")
+              );
+            } else if (result.status === "error") {
+              console.log(
+                chalk6.red("  \u2717"),
+                result.repo,
+                chalk6.red(`(${result.error})`)
+              );
+            }
+          }
+        }
+      }
+      const successful = results.filter((r) => r.status === "success");
+      const skipped = results.filter((r) => r.status === "skipped");
+      const failed = results.filter((r) => r.status === "error");
+      const totalFiles = successful.reduce((sum, r) => sum + (r.filesSynced || 0), 0);
+      if (options.json) {
+        console.log(JSON.stringify({
+          organization: org,
+          environment: options.env,
+          branch: targetBranch,
+          direction,
+          results: {
+            total: results.length,
+            successful: successful.length,
+            skipped: skipped.length,
+            failed: failed.length,
+            filesSynced: totalFiles,
+            details: results
+          }
+        }, null, 2));
+      } else {
+        console.log("");
+        console.log(chalk6.green(`\u2713 Synced ${successful.length}/${results.length} repos (${totalFiles} files)`));
+        if (skipped.length > 0) {
+          console.log(chalk6.dim(`  Skipped ${skipped.length} repos (no changes)`));
+        }
+        if (failed.length > 0) {
+          console.log(chalk6.red(`\u2717 ${failed.length} repos failed`));
+        }
+      }
+    } catch (error) {
+      if (options.json) {
+        console.log(JSON.stringify({ error: error.message }));
+      } else {
+        console.error(chalk6.red("Error:"), error.message);
+      }
+      process.exit(1);
+    }
+  });
+  return cmd;
+}
+
+// src/commands/sync/index.ts
+function syncCommand() {
+  const cmd = new Command("sync");
+  cmd.description("Synchronize with codex repository");
+  cmd.addCommand(syncProjectCommand());
+  cmd.addCommand(syncOrgCommand());
+  return cmd;
+}
+
+// src/commands/types/index.ts
+init_esm_shims();
+
+// src/commands/types/list.ts
+init_esm_shims();
+function formatTtl(seconds) {
+  if (seconds < 60) return `${seconds}s`;
+  if (seconds < 3600) return `${Math.floor(seconds / 60)}m`;
+  if (seconds < 86400) return `${Math.floor(seconds / 3600)}h`;
+  return `${Math.floor(seconds / 86400)}d`;
+}
+function typesListCommand() {
+  const cmd = new Command("list");
+  cmd.description("List all artifact types").option("--json", "Output as JSON").option("--custom-only", "Show only custom types").option("--builtin-only", "Show only built-in types").action(async (options) => {
+    try {
+      const client = await getClient();
+      const registry = client.getTypeRegistry();
+      const allTypes = registry.list();
+      let types = allTypes;
+      if (options.customOnly) {
+        types = allTypes.filter((t) => !registry.isBuiltIn(t.name));
+      } else if (options.builtinOnly) {
+        types = allTypes.filter((t) => registry.isBuiltIn(t.name));
+      }
+      if (options.json) {
+        const builtinCount = types.filter((t) => registry.isBuiltIn(t.name)).length;
+        const customCount = types.length - builtinCount;
+        console.log(JSON.stringify({
+          count: types.length,
+          builtinCount,
+          customCount,
+          types: types.map((t) => ({
+            name: t.name,
+            description: t.description,
+            patterns: t.patterns,
+            defaultTtl: t.defaultTtl,
+            ttl: formatTtl(t.defaultTtl),
+            builtin: registry.isBuiltIn(t.name),
+            archiveAfterDays: t.archiveAfterDays,
+            archiveStorage: t.archiveStorage
+          }))
+        }, null, 2));
+        return;
+      }
+      if (types.length === 0) {
+        console.log(chalk6.yellow("No types found."));
+        return;
+      }
+      console.log(chalk6.bold("Artifact Types\n"));
+      const builtinTypes = types.filter((t) => registry.isBuiltIn(t.name));
+      const customTypes = types.filter((t) => !registry.isBuiltIn(t.name));
+      if (builtinTypes.length > 0 && !options.customOnly) {
+        console.log(chalk6.bold("Built-in Types"));
+        console.log(chalk6.dim("\u2500".repeat(70)));
+        for (const type of builtinTypes) {
+          const patternStr = type.patterns[0] || "";
+          console.log(`  ${chalk6.cyan(type.name.padEnd(12))} ${patternStr.padEnd(30)} ${chalk6.dim(`TTL: ${formatTtl(type.defaultTtl)}`)}`);
+          console.log(`  ${chalk6.dim(" ".repeat(12) + type.description)}`);
+        }
+        console.log("");
+      }
+      if (customTypes.length > 0 && !options.builtinOnly) {
+        console.log(chalk6.bold("Custom Types"));
+        console.log(chalk6.dim("\u2500".repeat(70)));
+        for (const type of customTypes) {
+          const patternStr = type.patterns[0] || "";
+          console.log(`  ${chalk6.green(type.name.padEnd(12))} ${patternStr.padEnd(30)} ${chalk6.dim(`TTL: ${formatTtl(type.defaultTtl)}`)}`);
+          console.log(`  ${chalk6.dim(" ".repeat(12) + type.description)}`);
+        }
+        console.log("");
+      }
+      console.log(chalk6.dim(`Total: ${types.length} types (${builtinTypes.length} built-in, ${customTypes.length} custom)`));
+    } catch (error) {
+      console.error(chalk6.red("Error:"), error.message);
+      process.exit(1);
+    }
+  });
+  return cmd;
+}
+
+// src/commands/types/show.ts
+init_esm_shims();
+function formatTtl2(seconds) {
+  if (seconds < 60) return `${seconds}s`;
+  if (seconds < 3600) return `${Math.floor(seconds / 60)}m`;
+  if (seconds < 86400) return `${Math.floor(seconds / 3600)}h`;
+  return `${Math.floor(seconds / 86400)}d`;
+}
+function typesShowCommand() {
+  const cmd = new Command("show");
+  cmd.description("Show details for a specific type").argument("<name>", "Type name").option("--json", "Output as JSON").action(async (name, options) => {
+    try {
+      const client = await getClient();
+      const registry = client.getTypeRegistry();
+      const type = registry.get(name);
+      if (!type) {
+        console.error(chalk6.red("Error:"), `Type "${name}" not found.`);
+        console.log(chalk6.dim('Run "fractary codex types list" to see available types.'));
+        process.exit(1);
+      }
+      const isBuiltin = registry.isBuiltIn(name);
+      if (options.json) {
+        console.log(JSON.stringify({
+          name: type.name,
+          builtin: isBuiltin,
+          description: type.description,
+          patterns: type.patterns,
+          defaultTtl: type.defaultTtl,
+          ttl: formatTtl2(type.defaultTtl),
+          archiveAfterDays: type.archiveAfterDays,
+          archiveStorage: type.archiveStorage,
+          syncPatterns: type.syncPatterns,
+          excludePatterns: type.excludePatterns
+        }, null, 2));
+        return;
+      }
+      const nameColor = isBuiltin ? chalk6.cyan : chalk6.green;
+      console.log(chalk6.bold(`Type: ${nameColor(name)}
+`));
+      console.log(`  ${chalk6.dim("Source:")}      ${isBuiltin ? "Built-in" : "Custom"}`);
+      console.log(`  ${chalk6.dim("Description:")} ${type.description}`);
+      console.log(`  ${chalk6.dim("TTL:")}         ${formatTtl2(type.defaultTtl)} (${type.defaultTtl} seconds)`);
+      console.log("");
+      console.log(chalk6.bold("Patterns"));
+      for (const pattern of type.patterns) {
+        console.log(`  ${chalk6.dim("\u2022")} ${pattern}`);
+      }
+      if (type.archiveAfterDays !== null) {
+        console.log("");
+        console.log(chalk6.bold("Archive Settings"));
+        console.log(`  ${chalk6.dim("After:")}   ${type.archiveAfterDays} days`);
+        console.log(`  ${chalk6.dim("Storage:")} ${type.archiveStorage || "not set"}`);
+      }
+      if (type.syncPatterns && type.syncPatterns.length > 0) {
+        console.log("");
+        console.log(chalk6.bold("Sync Patterns"));
+        for (const pattern of type.syncPatterns) {
+          console.log(`  ${chalk6.dim("\u2022")} ${pattern}`);
+        }
+      }
+      if (type.excludePatterns && type.excludePatterns.length > 0) {
+        console.log("");
+        console.log(chalk6.bold("Exclude Patterns"));
+        for (const pattern of type.excludePatterns) {
+          console.log(`  ${chalk6.dim("\u2022")} ${pattern}`);
+        }
+      }
+    } catch (error) {
+      console.error(chalk6.red("Error:"), error.message);
+      process.exit(1);
+    }
+  });
+  return cmd;
+}
+
+// src/commands/types/add.ts
+init_esm_shims();
+init_migrate_config();
+function isValidTypeName(name) {
+  return /^[a-z][a-z0-9-]*$/.test(name);
+}
+function parseTtl(ttl) {
+  const match = ttl.match(/^(\d+)([smhd])$/);
+  if (!match) {
+    throw new Error("Invalid TTL format");
+  }
+  const value = parseInt(match[1], 10);
+  const unit = match[2];
+  switch (unit) {
+    case "s":
+      return value;
+    case "m":
+      return value * 60;
+    case "h":
+      return value * 3600;
+    case "d":
+      return value * 86400;
+    default:
+      throw new Error("Unknown TTL unit");
+  }
+}
+function formatTtl3(seconds) {
+  if (seconds < 60) return `${seconds}s`;
+  if (seconds < 3600) return `${Math.floor(seconds / 60)}m`;
+  if (seconds < 86400) return `${Math.floor(seconds / 3600)}h`;
+  return `${Math.floor(seconds / 86400)}d`;
+}
+function typesAddCommand() {
+  const cmd = new Command("add");
+  cmd.description("Add a custom artifact type").argument("<name>", "Type name (lowercase, alphanumeric with hyphens)").requiredOption("--pattern <glob>", "File pattern (glob syntax)").option("--ttl <duration>", 'Cache TTL (e.g., "24h", "7d")', "24h").option("--description <text>", "Type description").option("--json", "Output as JSON").action(async (name, options) => {
+    try {
+      if (!isValidTypeName(name)) {
+        console.error(chalk6.red("Error:"), "Invalid type name.");
+        console.log(chalk6.dim("Type name must be lowercase, start with a letter, and contain only letters, numbers, and hyphens."));
+        process.exit(1);
+      }
+      const client = await getClient();
+      const registry = client.getTypeRegistry();
+      if (registry.isBuiltIn(name)) {
+        console.error(chalk6.red("Error:"), `Cannot override built-in type "${name}".`);
+        const builtinNames = registry.list().filter((t) => registry.isBuiltIn(t.name)).map((t) => t.name);
+        console.log(chalk6.dim("Built-in types: " + builtinNames.join(", ")));
+        process.exit(1);
+      }
+      if (registry.has(name)) {
+        console.error(chalk6.red("Error:"), `Custom type "${name}" already exists.`);
+        console.log(chalk6.dim('Use "fractary codex types remove" first to remove it.'));
+        process.exit(1);
+      }
+      let ttlSeconds;
+      try {
+        ttlSeconds = parseTtl(options.ttl);
+      } catch {
+        console.error(chalk6.red("Error:"), "Invalid TTL format.");
+        console.log(chalk6.dim("Expected format: <number><unit> where unit is s (seconds), m (minutes), h (hours), or d (days)"));
+        console.log(chalk6.dim("Examples: 30m, 24h, 7d"));
+        process.exit(1);
+      }
+      const configPath = path3.join(process.cwd(), ".fractary", "codex.yaml");
+      const config = await readYamlConfig(configPath);
+      if (!config.types) {
+        config.types = { custom: {} };
+      }
+      if (!config.types.custom) {
+        config.types.custom = {};
+      }
+      config.types.custom[name] = {
+        description: options.description || `Custom type: ${name}`,
+        patterns: [options.pattern],
+        defaultTtl: ttlSeconds
+      };
+      await writeYamlConfig(config, configPath);
+      if (options.json) {
+        console.log(JSON.stringify({
+          success: true,
+          type: {
+            name,
+            description: config.types.custom[name].description,
+            patterns: config.types.custom[name].patterns,
+            defaultTtl: ttlSeconds,
+            ttl: formatTtl3(ttlSeconds),
+            builtin: false
+          },
+          message: "Custom type added successfully. Changes will take effect on next CLI invocation."
+        }, null, 2));
+        return;
+      }
+      console.log(chalk6.green("\u2713"), `Added custom type "${chalk6.cyan(name)}"`);
+      console.log("");
+      console.log(`  ${chalk6.dim("Pattern:")}     ${options.pattern}`);
+      console.log(`  ${chalk6.dim("TTL:")}         ${formatTtl3(ttlSeconds)} (${ttlSeconds} seconds)`);
+      if (options.description) {
+        console.log(`  ${chalk6.dim("Description:")} ${options.description}`);
+      }
+      console.log("");
+      console.log(chalk6.dim("Note: Custom type will be available on next CLI invocation."));
+    } catch (error) {
+      console.error(chalk6.red("Error:"), error.message);
+      if (error.message.includes("Failed to load configuration")) {
+        console.log(chalk6.dim('\nRun "fractary codex init" to create a configuration.'));
+      }
+      process.exit(1);
+    }
+  });
+  return cmd;
+}
+
+// src/commands/types/remove.ts
+init_esm_shims();
+init_migrate_config();
+function typesRemoveCommand() {
+  const cmd = new Command("remove");
+  cmd.description("Remove a custom artifact type").argument("<name>", "Type name to remove").option("--json", "Output as JSON").option("--force", "Skip confirmation").action(async (name, options) => {
+    try {
+      const client = await getClient();
+      const registry = client.getTypeRegistry();
+      if (registry.isBuiltIn(name)) {
+        console.error(chalk6.red("Error:"), `Cannot remove built-in type "${name}".`);
+        console.log(chalk6.dim("Built-in types are permanent and cannot be removed."));
+        process.exit(1);
+      }
+      if (!registry.has(name)) {
+        console.error(chalk6.red("Error:"), `Custom type "${name}" not found.`);
+        console.log(chalk6.dim('Run "fractary codex types list --custom-only" to see custom types.'));
+        process.exit(1);
+      }
+      const typeInfo = registry.get(name);
+      const configPath = path3.join(process.cwd(), ".fractary", "codex.yaml");
+      const config = await readYamlConfig(configPath);
+      if (!config.types?.custom?.[name]) {
+        console.error(chalk6.red("Error:"), `Custom type "${name}" not found in configuration.`);
+        process.exit(1);
+      }
+      delete config.types.custom[name];
+      if (Object.keys(config.types.custom).length === 0) {
+        delete config.types.custom;
+      }
+      if (config.types && Object.keys(config.types).length === 0) {
+        delete config.types;
+      }
+      await writeYamlConfig(config, configPath);
+      if (options.json) {
+        console.log(JSON.stringify({
+          success: true,
+          removed: {
+            name: typeInfo.name,
+            description: typeInfo.description,
+            patterns: typeInfo.patterns,
+            defaultTtl: typeInfo.defaultTtl
+          },
+          message: "Custom type removed successfully. Changes will take effect on next CLI invocation."
+        }, null, 2));
+        return;
+      }
+      console.log(chalk6.green("\u2713"), `Removed custom type "${chalk6.cyan(name)}"`);
+      console.log("");
+      console.log(chalk6.dim("Removed configuration:"));
+      console.log(`  ${chalk6.dim("Pattern:")}     ${typeInfo.patterns.join(", ")}`);
+      console.log(`  ${chalk6.dim("Description:")} ${typeInfo.description}`);
+      console.log("");
+      console.log(chalk6.dim("Note: Custom type will be removed on next CLI invocation."));
+    } catch (error) {
+      console.error(chalk6.red("Error:"), error.message);
+      if (error.message.includes("Failed to load configuration")) {
+        console.log(chalk6.dim('\nRun "fractary codex init" to create a configuration.'));
+      }
+      process.exit(1);
+    }
+  });
+  return cmd;
+}
+
+// src/commands/types/index.ts
+function typesCommand() {
+  const cmd = new Command("types");
+  cmd.description("Manage artifact type registry");
+  cmd.addCommand(typesListCommand());
+  cmd.addCommand(typesShowCommand());
+  cmd.addCommand(typesAddCommand());
+  cmd.addCommand(typesRemoveCommand());
+  return cmd;
+}
+
+// src/commands/health.ts
+init_esm_shims();
+init_migrate_config();
+async function fileExists2(filePath) {
+  try {
+    await fs.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function checkConfiguration() {
+  const configPath = path3.join(process.cwd(), ".fractary", "codex.yaml");
+  const legacyConfigPath = path3.join(process.cwd(), ".fractary", "plugins", "codex", "config.json");
+  try {
+    if (!await fileExists2(configPath)) {
+      if (await fileExists2(legacyConfigPath)) {
+        return {
+          name: "Configuration",
+          status: "warn",
+          message: "Legacy JSON configuration detected",
+          details: 'Run "fractary codex migrate" to upgrade to YAML format'
+        };
+      }
+      return {
+        name: "Configuration",
+        status: "fail",
+        message: "No configuration found",
+        details: 'Run "fractary codex init" to create configuration'
+      };
+    }
+    const config = await readYamlConfig(configPath);
+    if (!config.organization) {
+      return {
+        name: "Configuration",
+        status: "warn",
+        message: "No organization configured",
+        details: "Organization slug is required"
+      };
+    }
+    const providerCount = config.storage?.length || 0;
+    if (providerCount === 0) {
+      return {
+        name: "Configuration",
+        status: "warn",
+        message: "No storage providers configured",
+        details: "At least one storage provider is recommended"
+      };
+    }
+    return {
+      name: "Configuration",
+      status: "pass",
+      message: "Valid YAML configuration",
+      details: `Organization: ${config.organization}, ${providerCount} storage provider(s)`
+    };
+  } catch (error) {
+    return {
+      name: "Configuration",
+      status: "fail",
+      message: "Invalid configuration",
+      details: error.message
+    };
+  }
+}
+async function checkSDKClient() {
+  try {
+    const client = await getClient();
+    const organization = client.getOrganization();
+    return {
+      name: "SDK Client",
+      status: "pass",
+      message: "CodexClient initialized successfully",
+      details: `Organization: ${organization}`
+    };
+  } catch (error) {
+    return {
+      name: "SDK Client",
+      status: "fail",
+      message: "Failed to initialize CodexClient",
+      details: error.message
+    };
+  }
+}
+async function checkCache() {
+  try {
+    const client = await getClient();
+    const stats = await client.getCacheStats();
+    if (stats.entryCount === 0) {
+      return {
+        name: "Cache",
+        status: "warn",
+        message: "Cache is empty",
+        details: "Fetch some documents to populate cache"
+      };
+    }
+    const healthPercent = stats.entryCount > 0 ? stats.freshCount / stats.entryCount * 100 : 100;
+    if (healthPercent < 50) {
+      return {
+        name: "Cache",
+        status: "warn",
+        message: `${stats.entryCount} entries (${healthPercent.toFixed(0)}% fresh)`,
+        details: `${stats.expiredCount} expired, ${stats.staleCount} stale`
+      };
+    }
+    return {
+      name: "Cache",
+      status: "pass",
+      message: `${stats.entryCount} entries (${healthPercent.toFixed(0)}% fresh)`,
+      details: `${formatSize4(stats.totalSize)} total`
+    };
+  } catch (error) {
+    return {
+      name: "Cache",
+      status: "fail",
+      message: "Cache check failed",
+      details: error.message
+    };
+  }
+}
+async function checkStorage() {
+  const configPath = path3.join(process.cwd(), ".fractary", "codex.yaml");
+  try {
+    const config = await readYamlConfig(configPath);
+    const providers = config.storage || [];
+    if (providers.length === 0) {
+      return {
+        name: "Storage",
+        status: "warn",
+        message: "No storage providers configured",
+        details: "Configure at least one provider in .fractary/codex.yaml"
+      };
+    }
+    const providerTypes = providers.map((p) => p.type).join(", ");
+    const hasGitHub = providers.some((p) => p.type === "github");
+    if (hasGitHub && !process.env.GITHUB_TOKEN) {
+      return {
+        name: "Storage",
+        status: "warn",
+        message: `${providers.length} provider(s): ${providerTypes}`,
+        details: "GITHUB_TOKEN not set (required for GitHub provider)"
+      };
+    }
+    return {
+      name: "Storage",
+      status: "pass",
+      message: `${providers.length} provider(s): ${providerTypes}`,
+      details: "All configured providers available"
+    };
+  } catch (error) {
+    return {
+      name: "Storage",
+      status: "fail",
+      message: "Storage check failed",
+      details: error.message
+    };
+  }
+}
+async function checkTypes() {
+  try {
+    const client = await getClient();
+    const registry = client.getTypeRegistry();
+    const allTypes = registry.list();
+    const builtinCount = allTypes.filter((t) => registry.isBuiltIn(t.name)).length;
+    const customCount = allTypes.length - builtinCount;
+    return {
+      name: "Type Registry",
+      status: "pass",
+      message: `${allTypes.length} types registered`,
+      details: `${builtinCount} built-in, ${customCount} custom`
+    };
+  } catch (error) {
+    return {
+      name: "Type Registry",
+      status: "fail",
+      message: "Type registry check failed",
+      details: error.message
+    };
+  }
+}
+function formatSize4(bytes) {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+function healthCommand() {
+  const cmd = new Command("health");
+  cmd.description("Run diagnostics on codex setup").option("--json", "Output as JSON").action(async (options) => {
+    try {
+      const checks = [];
+      checks.push(await checkConfiguration());
+      checks.push(await checkSDKClient());
+      checks.push(await checkCache());
+      checks.push(await checkStorage());
+      checks.push(await checkTypes());
+      const passed = checks.filter((c) => c.status === "pass").length;
+      const warned = checks.filter((c) => c.status === "warn").length;
+      const failed = checks.filter((c) => c.status === "fail").length;
+      if (options.json) {
+        console.log(JSON.stringify({
+          summary: {
+            total: checks.length,
+            passed,
+            warned,
+            failed,
+            healthy: failed === 0
+          },
+          checks
+        }, null, 2));
+        return;
+      }
+      console.log(chalk6.bold("Codex Health Check\n"));
+      for (const check of checks) {
+        const icon = check.status === "pass" ? chalk6.green("\u2713") : check.status === "warn" ? chalk6.yellow("\u26A0") : chalk6.red("\u2717");
+        const statusColor = check.status === "pass" ? chalk6.green : check.status === "warn" ? chalk6.yellow : chalk6.red;
+        console.log(`${icon} ${chalk6.bold(check.name)}`);
+        console.log(`  ${statusColor(check.message)}`);
+        if (check.details) {
+          console.log(`  ${chalk6.dim(check.details)}`);
+        }
+        console.log("");
+      }
+      console.log(chalk6.dim("\u2500".repeat(60)));
+      const overallStatus = failed > 0 ? chalk6.red("UNHEALTHY") : warned > 0 ? chalk6.yellow("DEGRADED") : chalk6.green("HEALTHY");
+      console.log(`Status: ${overallStatus}`);
+      console.log(chalk6.dim(`${passed} passed, ${warned} warnings, ${failed} failed`));
+      if (failed > 0 || warned > 0) {
+        console.log("");
+        console.log(chalk6.dim("Run checks individually for more details:"));
+        console.log(chalk6.dim("  fractary codex cache stats"));
+        console.log(chalk6.dim("  fractary codex types list"));
+      }
+      if (failed > 0) {
+        process.exit(1);
+      }
+    } catch (error) {
+      console.error(chalk6.red("Error:"), error.message);
+      process.exit(1);
+    }
+  });
+  return cmd;
+}
+
+// src/commands/migrate.ts
+init_esm_shims();
+init_migrate_config();
+async function fileExists3(filePath) {
+  try {
+    await fs.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function readFileContent(filePath) {
+  return fs.readFile(filePath, "utf-8");
+}
+function migrateCommand() {
+  const cmd = new Command("migrate");
+  cmd.description("Migrate legacy JSON configuration to v3.0 YAML format").option("--dry-run", "Show migration plan without executing").option("--no-backup", "Skip creating backup of old config").option("--json", "Output as JSON").action(async (options) => {
+    try {
+      const legacyConfigPath = path3.join(process.cwd(), ".fractary", "plugins", "codex", "config.json");
+      const newConfigPath = path3.join(process.cwd(), ".fractary", "codex.yaml");
+      if (!await fileExists3(legacyConfigPath)) {
+        if (options.json) {
+          console.log(JSON.stringify({
+            status: "no_config",
+            message: "No legacy configuration file found",
+            path: legacyConfigPath
+          }));
+        } else {
+          console.log(chalk6.yellow("\u26A0 No legacy configuration file found."));
+          console.log(chalk6.dim(`  Expected: ${legacyConfigPath}`));
+          console.log(chalk6.dim('\nRun "fractary codex init" to create a new v3.0 YAML configuration.'));
+        }
+        return;
+      }
+      if (await fileExists3(newConfigPath) && !options.dryRun) {
+        if (options.json) {
+          console.log(JSON.stringify({
+            status: "already_migrated",
+            message: "YAML configuration already exists",
+            path: newConfigPath
+          }));
+        } else {
+          console.log(chalk6.yellow("\u26A0 YAML configuration already exists."));
+          console.log(chalk6.dim(`  Path: ${newConfigPath}`));
+          console.log(chalk6.dim('\nUse "fractary codex init --force" to recreate.'));
+        }
+        return;
+      }
+      const legacyContent = await readFileContent(legacyConfigPath);
+      let legacyConfig;
+      try {
+        legacyConfig = JSON.parse(legacyContent);
+      } catch {
+        console.error(chalk6.red("Error:"), "Invalid JSON in legacy config file.");
+        process.exit(1);
+      }
+      if (!options.json && !options.dryRun) {
+        console.log(chalk6.blue("Migrating Codex configuration to v3.0 YAML format...\n"));
+      }
+      const migrationResult = await migrateConfig(
+        legacyConfigPath,
+        {
+          createBackup: options.backup !== false,
+          backupSuffix: (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-")
+        }
+      );
+      if (!options.json) {
+        console.log(chalk6.bold("Legacy Configuration:"));
+        console.log(chalk6.dim(`  Path: ${legacyConfigPath}`));
+        console.log(chalk6.dim(`  Organization: ${legacyConfig.organization || legacyConfig.organizationSlug || "unknown"}`));
+        console.log("");
+        console.log(chalk6.bold("Migration Changes:"));
+        console.log(chalk6.green("  + Format: JSON \u2192 YAML"));
+        console.log(chalk6.green("  + Location: .fractary/plugins/codex/ \u2192 .fractary/"));
+        console.log(chalk6.green("  + File: config.json \u2192 codex.yaml"));
+        console.log(chalk6.green("  + Storage: Multi-provider configuration"));
+        console.log(chalk6.green("  + Cache: Modern cache management"));
+        console.log(chalk6.green("  + Types: Custom type registry"));
+        if (migrationResult.warnings.length > 0) {
+          console.log("");
+          console.log(chalk6.yellow("Warnings:"));
+          for (const warning of migrationResult.warnings) {
+            console.log(chalk6.yellow("  \u26A0"), chalk6.dim(warning));
+          }
+        }
+        console.log("");
+        if (options.dryRun) {
+          console.log(chalk6.blue("Dry run - no changes made."));
+          console.log(chalk6.dim("Run without --dry-run to execute migration."));
+          return;
+        }
+      }
+      if (options.json) {
+        const output = {
+          status: options.dryRun ? "migration_ready" : "migrated",
+          dryRun: options.dryRun || false,
+          legacyConfig: {
+            path: legacyConfigPath,
+            organization: legacyConfig.organization || legacyConfig.organizationSlug
+          },
+          newConfig: {
+            path: newConfigPath,
+            organization: migrationResult.yamlConfig.organization
+          },
+          warnings: migrationResult.warnings,
+          backupPath: migrationResult.backupPath
+        };
+        console.log(JSON.stringify(output, null, 2));
+        if (options.dryRun) {
+          return;
+        }
+      }
+      if (!options.dryRun) {
+        await writeYamlConfig(migrationResult.yamlConfig, newConfigPath);
+        const cacheDir = path3.join(process.cwd(), ".codex-cache");
+        await fs.mkdir(cacheDir, { recursive: true });
+        if (!options.json) {
+          console.log(chalk6.green("\u2713"), "YAML configuration created");
+          console.log(chalk6.green("\u2713"), "Cache directory initialized");
+          if (migrationResult.backupPath) {
+            console.log(chalk6.green("\u2713"), "Legacy config backed up");
+          }
+          console.log("");
+          console.log(chalk6.bold("New Configuration:"));
+          console.log(chalk6.dim(`  Path: ${newConfigPath}`));
+          console.log(chalk6.dim(`  Organization: ${migrationResult.yamlConfig.organization}`));
+          console.log(chalk6.dim(`  Cache: ${migrationResult.yamlConfig.cacheDir || ".codex-cache"}`));
+          console.log(chalk6.dim(`  Storage Providers: ${migrationResult.yamlConfig.storage?.length || 0}`));
+          console.log("");
+          console.log(chalk6.bold("Next Steps:"));
+          console.log(chalk6.dim("  1. Review the new configuration: .fractary/codex.yaml"));
+          console.log(chalk6.dim('  2. Set your GitHub token: export GITHUB_TOKEN="your_token"'));
+          console.log(chalk6.dim("  3. Test fetching: fractary codex fetch codex://org/project/path"));
+          if (migrationResult.backupPath) {
+            console.log("");
+            console.log(chalk6.dim(`Backup saved: ${path3.basename(migrationResult.backupPath)}`));
+          }
+        }
+      }
+    } catch (error) {
+      if (options.json) {
+        console.log(JSON.stringify({
+          status: "error",
+          message: error.message
+        }));
+      } else {
+        console.error(chalk6.red("Error:"), error.message);
+      }
+      process.exit(1);
+    }
+  });
+  return cmd;
+}
+
+// src/cli.ts
+function createCLI() {
+  const program = new Command("fractary-codex");
+  program.description("Centralized knowledge management and distribution for AI agents").version("0.2.0");
+  program.addCommand(initCommand());
+  program.addCommand(fetchCommand());
+  program.addCommand(cacheCommand());
+  program.addCommand(syncCommand());
+  program.addCommand(typesCommand());
+  program.addCommand(healthCommand());
+  program.addCommand(migrateCommand());
+  return program;
+}
+async function main() {
+  try {
+    const program = createCLI();
+    await program.parseAsync(process.argv);
+  } catch (error) {
+    console.error("Error:", error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  }
+}
+main();
+//# sourceMappingURL=cli.js.map
+//# sourceMappingURL=cli.js.map