@fractary/codex-cli 0.10.16 → 0.10.19

package/dist/cli.js

@@ -1,25 +1,19 @@
 #!/usr/bin/env node
-import * as path3 from 'path';
+import * as path4 from 'path';
 import { dirname, join } from 'path';
 import { fileURLToPath } from 'url';
-import * as fs4 from 'fs/promises';
-import * as yaml from 'js-yaml';
-import { readCodexConfig, CONFIG_SCHEMA_VERSION, expandEnvVarsInConfig, expandEnvVars, parseSize, parseDuration, ValidationError, PermissionDeniedError, ConfigurationError, CodexError } from '@fractary/codex';
+import { createConfigManager, resolveOrganization, validateNameFormat, formatBytes, createHealthChecker, readCodexConfig, formatDuration, createCodexClient, ValidationError, PermissionDeniedError, ConfigurationError, CodexError, CodexClient } from '@fractary/codex';
 import * as os from 'os';
+import * as fs2 from 'fs/promises';
 import { spawn } from 'child_process';
 import { Command } from 'commander';
-import chalk7 from 'chalk';
+import chalk10 from 'chalk';
 import * as crypto from 'crypto';
+import 'js-yaml';
 import { readFileSync } from 'fs';
 
 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;
 };
@@ -32,222 +26,6 @@ var init_esm_shims = __esm({
   }
 });
 
-// src/config/migrate-config.ts
-var migrate_config_exports = {};
-__export(migrate_config_exports, {
-  getDefaultYamlConfig: () => getDefaultYamlConfig,
-  isLegacyConfig: () => isLegacyConfig,
-  migrateConfig: () => migrateConfig,
-  readYamlConfig: () => readCodexConfig,
-  writeYamlConfig: () => writeYamlConfig
-});
-async function isLegacyConfig(configPath) {
-  try {
-    const content = await fs4.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 fs4.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 fs4.writeFile(backupPath, content, "utf-8");
-    }
-    const yamlConfig = {
-      organization: legacy.organization || legacy.organizationSlug || "default"
-    };
-    if (legacy.cache) {
-      yamlConfig.cacheDir = legacy.cache.directory || ".fractary/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 fs4.mkdir(dir, { recursive: true });
-  const yamlContent = yaml.dump(config, {
-    indent: 2,
-    lineWidth: 80,
-    noRefs: true,
-    sortKeys: false
-  });
-  await fs4.writeFile(outputPath, yamlContent, "utf-8");
-}
-function getDefaultYamlConfig(organization) {
-  return {
-    organization,
-    cacheDir: ".fractary/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
-    }
-  };
-}
-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: () => expandEnvVars,
-  resolveEnvVarsInConfig: () => expandEnvVarsInConfig
-});
-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, {
@@ -255,254 +33,12 @@ __export(codex_client_exports, {
   CodexError: () => CodexError,
   ConfigurationError: () => ConfigurationError,
   PermissionDeniedError: () => PermissionDeniedError,
-  ValidationError: () => ValidationError
+  ValidationError: () => ValidationError,
+  createCodexClient: () => createCodexClient
 });
-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 } = await Promise.resolve().then(() => (init_migrate_config(), migrate_config_exports));
-        const { resolveEnvVarsInConfig } = await Promise.resolve().then(() => (init_config_types(), config_types_exports));
-        try {
-          const configPath = path3.join(process.cwd(), ".fractary", "config.yaml");
-          let config;
-          try {
-            config = await readYamlConfig(configPath);
-            config = resolveEnvVarsInConfig(config);
-          } catch (error) {
-            throw new ConfigurationError2(
-              `Failed to load configuration from ${configPath}. Run "fractary-codex configure" 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;
-      }
-    };
   }
 });
 
@@ -567,7 +103,7 @@ function getTempCodexPath(config) {
   const codexRepo = config.codex_repo || "codex";
   const sanitizedOrg = sanitizePathComponent(config.organization);
   const sanitizedRepo = sanitizePathComponent(codexRepo);
-  return path3.join(
+  return path4.join(
     os.tmpdir(),
     "fractary-codex-clone",
     `${sanitizedOrg}-${sanitizedRepo}-${process.pid}`
@@ -575,8 +111,8 @@ function getTempCodexPath(config) {
 }
 async function isValidGitRepo(repoPath) {
   try {
-    const gitDir = path3.join(repoPath, ".git");
-    const stats = await fs4.stat(gitDir);
+    const gitDir = path4.join(repoPath, ".git");
+    const stats = await fs2.stat(gitDir);
     return stats.isDirectory();
   } catch {
     return false;
@@ -608,8 +144,8 @@ async function execGit(repoPath, args) {
   }
 }
 async function gitClone(url, targetPath, options) {
-  const parentDir = path3.dirname(targetPath);
-  await fs4.mkdir(parentDir, { recursive: true });
+  const parentDir = path4.dirname(targetPath);
+  await fs2.mkdir(parentDir, { recursive: true });
   const args = ["clone"];
   if (options?.depth) {
     if (!Number.isInteger(options.depth) || options.depth <= 0) {
@@ -656,12 +192,12 @@ async function ensureCodexCloned(config, options) {
     } catch (error) {
       console.warn(`Failed to update existing clone: ${error.message}`);
       console.warn(`Removing and cloning fresh...`);
-      await fs4.rm(tempPath, { recursive: true, force: true });
+      await fs2.rm(tempPath, { recursive: true, force: true });
     }
   }
   const repoUrl = getCodexRepoUrl(config);
   try {
-    await fs4.rm(tempPath, { recursive: true, force: true });
+    await fs2.rm(tempPath, { recursive: true, force: true });
   } catch (error) {
     console.warn(`Could not remove existing directory ${tempPath}: ${error.message}`);
   }
@@ -684,539 +220,304 @@ init_esm_shims();
 // src/commands/config/index.ts
 init_esm_shims();
 
-// src/commands/config/init.ts
-init_esm_shims();
-
-// src/config/unified-config.ts
+// src/commands/config/initialize.ts
 init_esm_shims();
-function sanitizeForS3BucketName(name) {
-  return name.toLowerCase().replace(/[^a-z0-9-]/g, "-").replace(/^-+|-+$/g, "").replace(/-+/g, "-").substring(0, 63);
-}
-function getDefaultUnifiedConfig(organization, project, codexRepo) {
-  const sanitizedProject = sanitizeForS3BucketName(project);
-  return {
-    file: {
-      schema_version: CONFIG_SCHEMA_VERSION,
-      sources: {
-        specs: {
-          type: "s3",
-          bucket: `${sanitizedProject}-files`,
-          prefix: "specs/",
-          region: "us-east-1",
-          local: {
-            base_path: ".fractary/specs"
-          },
-          push: {
-            compress: false,
-            keep_local: true
-          },
-          auth: {
-            profile: "default"
-          }
-        },
-        logs: {
-          type: "s3",
-          bucket: `${sanitizedProject}-files`,
-          prefix: "logs/",
-          region: "us-east-1",
-          local: {
-            base_path: ".fractary/logs"
-          },
-          push: {
-            compress: true,
-            keep_local: true
-          },
-          auth: {
-            profile: "default"
-          }
-        }
-      }
-    },
-    codex: {
-      schema_version: CONFIG_SCHEMA_VERSION,
-      organization,
-      project,
-      codex_repo: codexRepo,
-      remotes: {
-        // The codex repository - uses same token as git operations
-        [`${organization}/${codexRepo}`]: {
-          token: "${GITHUB_TOKEN}"
-        }
-      }
-    }
-  };
-}
-async function readUnifiedConfig(configPath) {
-  try {
-    const content = await fs4.readFile(configPath, "utf-8");
-    const config = yaml.load(content);
-    return config;
-  } catch (error) {
-    if (error.code === "ENOENT") {
-      return null;
-    }
-    throw error;
-  }
-}
-async function writeUnifiedConfig(config, outputPath) {
-  const dir = path3.dirname(outputPath);
-  await fs4.mkdir(dir, { recursive: true });
-  const yamlContent = yaml.dump(config, {
-    indent: 2,
-    lineWidth: 120,
-    noRefs: true,
-    sortKeys: false
-  });
-  await fs4.writeFile(outputPath, yamlContent, "utf-8");
-}
-function mergeUnifiedConfigs(existing, updates) {
-  const merged = {};
-  if (updates.file || existing.file) {
-    merged.file = {
-      schema_version: updates.file?.schema_version || existing.file?.schema_version || CONFIG_SCHEMA_VERSION,
-      sources: {
-        ...existing.file?.sources || {},
-        ...updates.file?.sources || {}
-      }
-    };
-  }
-  if (updates.codex || existing.codex) {
-    merged.codex = {
-      schema_version: updates.codex?.schema_version || existing.codex?.schema_version || CONFIG_SCHEMA_VERSION,
-      organization: updates.codex?.organization || existing.codex?.organization || "default",
-      project: updates.codex?.project || existing.codex?.project || "default",
-      codex_repo: updates.codex?.codex_repo || existing.codex?.codex_repo || "",
-      remotes: {
-        ...existing.codex?.remotes || {},
-        ...updates.codex?.remotes || {}
-      }
-    };
-  }
-  return merged;
-}
-async function initializeUnifiedConfig(configPath, organization, project, codexRepo, options) {
-  const existingConfig = await readUnifiedConfig(configPath);
-  if (existingConfig && !options?.force) {
-    const defaultConfig = getDefaultUnifiedConfig(organization, project, codexRepo);
-    const merged = mergeUnifiedConfigs(existingConfig, defaultConfig);
-    await writeUnifiedConfig(merged, configPath);
-    return {
-      created: false,
-      merged: true,
-      config: merged
-    };
-  }
-  const config = getDefaultUnifiedConfig(organization, project, codexRepo);
-  await writeUnifiedConfig(config, configPath);
-  return {
-    created: true,
-    merged: false,
-    config
-  };
-}
-
-// src/config/gitignore-utils.ts
-init_esm_shims();
-var DEFAULT_FRACTARY_GITIGNORE = `# .fractary/.gitignore
-# This file is managed by multiple plugins - each plugin manages its own section
-
-# ===== fractary-codex (managed) =====
-codex/cache/
-# ===== end fractary-codex =====
-`;
-async function readFractaryGitignore(projectRoot) {
-  const gitignorePath = path3.join(projectRoot, ".fractary", ".gitignore");
-  try {
-    return await fs4.readFile(gitignorePath, "utf-8");
-  } catch (error) {
-    if (error.code === "ENOENT") {
-      return null;
-    }
-    throw error;
-  }
-}
-async function writeFractaryGitignore(projectRoot, content) {
-  const gitignorePath = path3.join(projectRoot, ".fractary", ".gitignore");
-  await fs4.mkdir(path3.join(projectRoot, ".fractary"), { recursive: true });
-  await fs4.writeFile(gitignorePath, content, "utf-8");
-}
-function normalizeCachePath(cachePath) {
-  let normalized = cachePath.replace(/\\/g, "/");
-  normalized = normalized.replace(/^\.fractary\//, "");
-  if (!normalized.endsWith("/")) {
-    normalized += "/";
-  }
-  return normalized;
-}
-function isCachePathIgnored(gitignoreContent, cachePath) {
-  const normalized = normalizeCachePath(cachePath);
-  const lines = gitignoreContent.split("\n").map((l) => l.trim());
-  return lines.some((line) => {
-    if (line.startsWith("#") || line === "") return false;
-    let normalizedLine = line.replace(/\\/g, "/");
-    if (!normalizedLine.endsWith("/")) {
-      normalizedLine += "/";
-    }
-    return normalizedLine === normalized;
-  });
-}
-function addCachePathToGitignore(gitignoreContent, cachePath, comment) {
-  const normalized = normalizeCachePath(cachePath);
-  if (isCachePathIgnored(gitignoreContent, cachePath)) {
-    return gitignoreContent;
-  }
-  let addition = "";
-  {
-    addition += `
-# ${comment}
-`;
-  }
-  addition += normalized + "\n";
-  return gitignoreContent.trimEnd() + addition;
-}
-async function ensureCachePathIgnored(projectRoot, cachePath) {
-  const gitignorePath = path3.join(projectRoot, ".fractary", ".gitignore");
-  let relativeCachePath = cachePath;
-  if (path3.isAbsolute(cachePath)) {
-    relativeCachePath = path3.relative(path3.join(projectRoot, ".fractary"), cachePath);
-  }
-  relativeCachePath = normalizeCachePath(relativeCachePath);
-  let content = await readFractaryGitignore(projectRoot);
-  const gitignoreExists = content !== null;
-  if (!gitignoreExists) {
-    content = DEFAULT_FRACTARY_GITIGNORE;
-    if (!isCachePathIgnored(content, relativeCachePath)) {
-      content = addCachePathToGitignore(content, relativeCachePath, "Custom cache directory");
-    }
-    await writeFractaryGitignore(projectRoot, content);
-    return {
-      created: true,
-      updated: false,
-      alreadyIgnored: false,
-      gitignorePath
-    };
-  }
-  if (isCachePathIgnored(content, relativeCachePath)) {
-    return {
-      created: false,
-      updated: false,
-      alreadyIgnored: true,
-      gitignorePath
-    };
-  }
-  content = addCachePathToGitignore(content, relativeCachePath, "Custom cache directory");
-  await writeFractaryGitignore(projectRoot, content);
-  return {
-    created: false,
-    updated: true,
-    alreadyIgnored: false,
-    gitignorePath
-  };
-}
-
-// src/commands/config/init.ts
-function validateNameFormat(name, type) {
-  if (!name || typeof name !== "string") {
-    throw new Error(`${type} name is required`);
-  }
-  if (name.length > 100) {
-    throw new Error(`${type} name too long (max 100 characters)`);
-  }
-  const safePattern = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/;
-  if (!safePattern.test(name)) {
-    throw new Error(
-      `Invalid ${type} name format: "${name}". Must start with alphanumeric and contain only: a-z, A-Z, 0-9, ., -, _`
-    );
-  }
-}
-async function getOrgFromGitRemote() {
-  try {
-    const { execSync } = __require("child_process");
-    const remote = execSync("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 discoverCodexRepo(org) {
-  try {
-    validateNameFormat(org, "organization");
-  } catch (error) {
-    return { repo: null, error: "unknown", message: error.message };
-  }
-  try {
-    const { execSync } = __require("child_process");
-    try {
-      execSync("gh --version", { encoding: "utf-8", stdio: "pipe" });
-    } catch {
-      return {
-        repo: null,
-        error: "gh_not_installed",
-        message: "GitHub CLI (gh) is not installed. Install from https://cli.github.com/"
-      };
-    }
-    try {
-      execSync("gh auth status", { encoding: "utf-8", stdio: "pipe" });
-    } catch {
-      return {
-        repo: null,
-        error: "auth_failed",
-        message: "GitHub CLI not authenticated. Run: gh auth login"
-      };
-    }
-    const result = execSync(
-      `gh repo list ${org} --json name --jq '.[].name | select(startswith("codex."))' 2>&1`,
-      { encoding: "utf-8" }
-    ).trim();
-    if (result.includes("Could not resolve to an Organization") || result.includes("Not Found")) {
-      return {
-        repo: null,
-        error: "org_not_found",
-        message: `Organization '${org}' not found on GitHub`
-      };
-    }
-    const repos = result.split("\n").filter(Boolean);
-    if (repos.length === 0) {
-      return {
-        repo: null,
-        error: "no_repos_found",
-        message: `No codex.* repositories found in organization '${org}'`
-      };
-    }
-    return { repo: repos[0] };
-  } catch (error) {
-    return {
-      repo: null,
-      error: "unknown",
-      message: error.message || "Unknown error during discovery"
-    };
-  }
-}
-async function fileExists(filePath) {
-  try {
-    await fs4.access(filePath);
-    return true;
-  } catch {
-    return false;
-  }
-}
-async function installMcpServer(projectRoot, configPath = ".fractary/config.yaml", options = {}) {
-  const mcpJsonPath = path3.join(projectRoot, ".mcp.json");
-  const { backup = true } = options;
-  let existingConfig = { mcpServers: {} };
-  let backupPath;
-  let migrated = false;
-  if (await fileExists(mcpJsonPath)) {
+function configInitializeCommand() {
+  const cmd = new Command("config-initialize");
+  cmd.description("Initialize codex section in .fractary/config.yaml (requires base config from @fractary/core)").option("--org <slug>", 'Organization slug (e.g., "fractary")').option("--project <name>", "Project name (default: derived from directory)").option("--codex-repo <name>", 'Codex repository name (e.g., "codex.fractary.com")').option("--sync-preset <name>", "Sync preset (standard, minimal)", "standard").option("--force", "Overwrite existing codex section").option("--no-mcp", "Skip MCP server installation").option("--json", "Output as JSON").action(async (options) => {
     try {
-      const content = await fs4.readFile(mcpJsonPath, "utf-8");
-      existingConfig = JSON.parse(content);
-      if (backup) {
-        const timestamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "").slice(0, 18);
-        const suffix = Math.random().toString(36).substring(2, 6);
-        backupPath = `${mcpJsonPath}.backup.${timestamp}-${suffix}`;
-        await fs4.writeFile(backupPath, content);
-      }
-    } catch {
-      console.log(chalk7.yellow("\u26A0 Warning: .mcp.json contains invalid JSON, starting fresh"));
-      existingConfig = { mcpServers: {} };
-    }
-  }
-  if (!existingConfig.mcpServers) {
-    existingConfig.mcpServers = {};
-  }
-  const existing = existingConfig.mcpServers["fractary-codex"];
-  if (existing) {
-    const existingCommand = existing.command;
-    const existingArgs = existing.args || [];
-    if (existingCommand === "npx" && existingArgs.includes("@fractary/codex-mcp")) {
-      return {
-        installed: false,
-        migrated: false,
-        alreadyInstalled: true,
-        backupPath
-      };
-    }
-    if (existingCommand === "node" || existingArgs.includes("@fractary/codex")) {
-      migrated = true;
-    }
-  }
-  existingConfig.mcpServers["fractary-codex"] = {
-    command: "npx",
-    args: ["-y", "@fractary/codex-mcp", "--config", configPath]
-  };
-  await fs4.writeFile(
-    mcpJsonPath,
-    JSON.stringify(existingConfig, null, 2) + "\n"
-  );
-  return {
-    installed: true,
-    migrated,
-    alreadyInstalled: false,
-    backupPath
-  };
-}
-function configureCommand() {
-  const cmd = new Command("configure");
-  cmd.description("Initialize unified Fractary configuration (.fractary/config.yaml)").option("--org <slug>", 'Organization slug (e.g., "fractary")').option("--project <name>", "Project name (default: derived from directory)").option("--codex-repo <name>", 'Codex repository name (e.g., "codex.fractary.com")').option("--force", "Overwrite existing configuration").option("--no-mcp", "Skip MCP server installation").action(async (options) => {
-    try {
-      console.log(chalk7.blue("Initializing unified Fractary configuration...\n"));
+      const configManager = createConfigManager(process.cwd());
+      if (!options.json) {
+        console.log(chalk10.blue("Initializing codex configuration...\n"));
+      }
       let org = options.org;
       if (!org) {
-        org = await getOrgFromGitRemote();
+        org = await configManager.detectOrganization();
       }
       if (!org) {
         try {
-          const { resolveOrganization } = await import('@fractary/codex');
           org = resolveOrganization({
-            repoName: path3.basename(process.cwd())
+            repoName: path4.basename(process.cwd())
           });
         } catch {
         }
       }
       if (!org) {
-        org = path3.basename(process.cwd()).split("-")[0] || "default";
-        console.log(chalk7.yellow(`\u26A0 Could not detect organization, using: ${org}`));
-        console.log(chalk7.dim("  Use --org <slug> to specify explicitly\n"));
-      } else {
-        console.log(chalk7.dim(`Organization: ${chalk7.cyan(org)}
+        org = path4.basename(process.cwd()).split("-")[0] || "default";
+        if (!options.json) {
+          console.log(chalk10.yellow(`\u26A0 Could not detect organization, using: ${org}`));
+          console.log(chalk10.dim("  Use --org <slug> to specify explicitly\n"));
+        }
+      } else if (!options.json) {
+        console.log(chalk10.dim(`Organization: ${chalk10.cyan(org)}
 `));
       }
-      try {
-        validateNameFormat(org, "organization");
-      } catch (error) {
-        console.error(chalk7.red("Error:"), error.message);
+      const orgValidation = validateNameFormat(org, "organization");
+      if (!orgValidation.valid) {
+        if (options.json) {
+          console.log(JSON.stringify({ error: orgValidation.error }, null, 2));
+        } else {
+          console.error(chalk10.red("Error:"), orgValidation.error);
+        }
         process.exit(1);
       }
       let project = options.project;
       if (!project) {
-        project = path3.basename(process.cwd());
-        console.log(chalk7.dim(`Project: ${chalk7.cyan(project)}
+        project = configManager.detectProject();
+        if (!options.json) {
+          console.log(chalk10.dim(`Project: ${chalk10.cyan(project)}
 `));
+        }
       }
       let codexRepo = options.codexRepo;
       if (codexRepo) {
-        try {
-          validateNameFormat(codexRepo, "repository");
-        } catch (error) {
-          console.error(chalk7.red("Error:"), error.message);
+        const repoValidation = validateNameFormat(codexRepo, "repository");
+        if (!repoValidation.valid) {
+          if (options.json) {
+            console.log(JSON.stringify({ error: repoValidation.error }, null, 2));
+          } else {
+            console.error(chalk10.red("Error:"), repoValidation.error);
+          }
           process.exit(1);
         }
-        console.log(chalk7.dim(`Codex repository: ${chalk7.cyan(codexRepo)}
+        if (!options.json) {
+          console.log(chalk10.dim(`Codex repository: ${chalk10.cyan(codexRepo)}
 `));
+        }
       } else {
-        const discoveryResult = await discoverCodexRepo(org);
+        const discoveryResult = await configManager.discoverCodexRepo(org);
         if (discoveryResult.repo) {
           codexRepo = discoveryResult.repo;
-          console.log(chalk7.dim(`Codex repository: ${chalk7.cyan(codexRepo)} (auto-discovered)
-`));
-        } else {
-          if (discoveryResult.error === "gh_not_installed") {
-            console.log(chalk7.dim(`  Note: ${discoveryResult.message}
-`));
-          } else if (discoveryResult.error === "auth_failed") {
-            console.log(chalk7.dim(`  Note: ${discoveryResult.message}
+          if (!options.json) {
+            console.log(chalk10.dim(`Codex repository: ${chalk10.cyan(codexRepo)} (auto-discovered)
 `));
-          } else if (discoveryResult.error === "org_not_found") {
-            console.log(chalk7.dim(`  Note: ${discoveryResult.message}
+          }
+        } else if (!options.json) {
+          if (discoveryResult.message) {
+            console.log(chalk10.dim(`  Note: ${discoveryResult.message}
 `));
           }
         }
       }
       if (!codexRepo) {
-        console.log(chalk7.yellow(`\u26A0 Could not discover codex repository in organization '${org}'`));
-        console.log(chalk7.dim("  Use --codex-repo <name> to specify explicitly"));
-        console.log(chalk7.dim("  Expected naming convention: codex.{org}.{tld} (e.g., codex.fractary.com)\n"));
         codexRepo = `codex.${org}.com`;
-        console.log(chalk7.dim(`  Using default: ${chalk7.cyan(codexRepo)}
+        if (!options.json) {
+          console.log(chalk10.yellow(`\u26A0 Could not discover codex repository in organization '${org}'`));
+          console.log(chalk10.dim(`  Using default: ${chalk10.cyan(codexRepo)}
 `));
+        }
       }
-      const configPath = path3.join(process.cwd(), ".fractary", "config.yaml");
-      const configExists = await fileExists(configPath);
-      if (configExists && !options.force) {
-        console.log(chalk7.yellow(`\u26A0 Configuration already exists at .fractary/config.yaml`));
-        console.log(chalk7.dim("Merging with existing configuration...\n"));
-      }
-      console.log("Creating directory structure...");
-      const dirs = [
-        ".fractary",
-        ".fractary/specs",
-        ".fractary/logs",
-        ".fractary/codex",
-        ".fractary/codex/cache"
-      ];
-      for (const dir of dirs) {
-        await fs4.mkdir(path3.join(process.cwd(), dir), { recursive: true });
-        console.log(chalk7.green("\u2713"), chalk7.dim(dir + "/"));
-      }
-      const gitignoreResult = await ensureCachePathIgnored(process.cwd(), ".fractary/codex/cache");
-      if (gitignoreResult.created) {
-        console.log(chalk7.green("\u2713"), chalk7.dim(".fractary/.gitignore (created)"));
-      } else if (gitignoreResult.updated) {
-        console.log(chalk7.green("\u2713"), chalk7.dim(".fractary/.gitignore (updated)"));
-      } else {
-        console.log(chalk7.green("\u2713"), chalk7.dim(".fractary/.gitignore (exists)"));
-      }
-      console.log("\nInitializing configuration...");
-      const result = await initializeUnifiedConfig(
-        configPath,
-        org,
+      const result = await configManager.initializeCodexSection({
+        organization: org,
         project,
         codexRepo,
-        { force: options.force }
-      );
-      if (result.created) {
-        console.log(chalk7.green("\u2713"), chalk7.dim(".fractary/config.yaml (created)"));
-      } else if (result.merged) {
-        console.log(chalk7.green("\u2713"), chalk7.dim(".fractary/config.yaml (merged with existing)"));
-      }
-      if (options.mcp !== false) {
-        console.log("\nConfiguring MCP server...");
-        const mcpResult = await installMcpServer(process.cwd(), ".fractary/config.yaml");
-        if (mcpResult.alreadyInstalled) {
-          console.log(chalk7.green("\u2713"), chalk7.dim(".mcp.json (already configured)"));
-        } else if (mcpResult.migrated) {
-          console.log(chalk7.green("\u2713"), chalk7.dim(".mcp.json (migrated from old format)"));
-          if (mcpResult.backupPath) {
-            console.log(chalk7.dim(`  Backup: ${path3.basename(mcpResult.backupPath)}`));
-          }
-        } else if (mcpResult.installed) {
-          console.log(chalk7.green("\u2713"), chalk7.dim(".mcp.json (created)"));
+        syncPreset: options.syncPreset,
+        force: options.force,
+        skipMcp: options.mcp === false
+      });
+      if (options.json) {
+        console.log(
+          JSON.stringify(
+            {
+              success: true,
+              configPath: result.configPath,
+              codexSectionCreated: result.codexSectionCreated,
+              organization: org,
+              project,
+              codexRepo,
+              directories: result.directories,
+              gitignore: result.gitignore,
+              mcp: result.mcp
+            },
+            null,
+            2
+          )
+        );
+        return;
+      }
+      console.log("Setting up codex directories...");
+      for (const dir of result.directories.created) {
+        console.log(chalk10.green("\u2713"), chalk10.dim(dir + "/"));
+      }
+      for (const dir of result.directories.alreadyExisted) {
+        console.log(chalk10.dim("  " + dir + "/ (exists)"));
+      }
+      if (result.gitignore.created) {
+        console.log(chalk10.green("\u2713"), chalk10.dim(".fractary/.gitignore (created)"));
+      } else if (result.gitignore.updated) {
+        console.log(chalk10.green("\u2713"), chalk10.dim(".fractary/.gitignore (updated)"));
+      } else {
+        console.log(chalk10.green("\u2713"), chalk10.dim(".fractary/.gitignore (exists)"));
+      }
+      console.log(chalk10.green("\u2713"), chalk10.dim(".fractary/config.yaml (codex section added)"));
+      if (result.mcp) {
+        if (result.mcp.alreadyInstalled) {
+          console.log(chalk10.green("\u2713"), chalk10.dim(".mcp.json (already configured)"));
+        } else if (result.mcp.migrated) {
+          console.log(chalk10.green("\u2713"), chalk10.dim(".mcp.json (migrated from old format)"));
+        } else if (result.mcp.installed) {
+          console.log(chalk10.green("\u2713"), chalk10.dim(".mcp.json (created)"));
         }
       }
-      console.log(chalk7.green("\n\u2713 Unified configuration initialized successfully!\n"));
-      console.log(chalk7.bold("Configuration:"));
-      console.log(chalk7.dim(`  Organization: ${org}`));
-      console.log(chalk7.dim(`  Project: ${project}`));
-      console.log(chalk7.dim(`  Codex Repository: ${codexRepo}`));
-      console.log(chalk7.dim(`  Config: .fractary/config.yaml`));
-      console.log(chalk7.bold("\nFile plugin sources:"));
-      console.log(chalk7.dim("  - specs: .fractary/specs/ \u2192 S3"));
-      console.log(chalk7.dim("  - logs: .fractary/logs/ \u2192 S3"));
-      console.log(chalk7.bold("\nCodex plugin:"));
-      console.log(chalk7.dim("  - Cache: .fractary/codex/cache/"));
-      console.log(chalk7.dim("  - MCP Server: @fractary/codex-mcp (via npx)"));
-      console.log(chalk7.dim("  - Remotes: codex repo configured"));
-      console.log(chalk7.bold("\nGit Authentication:"));
-      console.log(chalk7.dim("  Codex sync uses your existing git credentials."));
-      console.log(chalk7.dim("  Ensure you have access to the codex repository:"));
-      console.log(chalk7.dim(`    gh repo view ${org}/${codexRepo}`));
-      console.log(chalk7.dim("  Or set GITHUB_TOKEN environment variable."));
-      console.log(chalk7.bold("\nNext steps:"));
-      console.log(chalk7.dim("  1. Restart Claude Code to load the MCP server"));
-      console.log(chalk7.dim("  2. Verify codex repository access: gh repo view " + org + "/" + codexRepo));
-      console.log(chalk7.dim("  3. Configure AWS credentials for S3 access (if using file plugin)"));
-      console.log(chalk7.dim("  4. Edit .fractary/config.yaml to add external project remotes"));
-      console.log(chalk7.dim("  5. Reference docs via codex:// URIs (auto-fetched by MCP)"));
+      console.log(chalk10.green("\n\u2713 Codex configuration initialized successfully!\n"));
+      console.log(chalk10.bold("Configuration:"));
+      console.log(chalk10.dim(`  Organization: ${org}`));
+      console.log(chalk10.dim(`  Project: ${project}`));
+      console.log(chalk10.dim(`  Codex Repository: ${codexRepo}`));
+      console.log(chalk10.bold("\nNext steps:"));
+      console.log(chalk10.dim("  1. Restart Claude Code to load the MCP server"));
+      console.log(chalk10.dim(`  2. Verify codex repository access: gh repo view ${org}/${codexRepo}`));
+      console.log(chalk10.dim("  3. Run first sync: /fractary-codex:sync --from-codex --dry-run"));
     } catch (error) {
-      console.error(chalk7.red("Error:"), error.message);
+      if (options.json) {
+        console.log(JSON.stringify({ error: error.message }, null, 2));
+      } else {
+        console.error(chalk10.red("Error:"), error.message);
+      }
       process.exit(1);
     }
   });
   return cmd;
 }
 
+// src/commands/config/update.ts
+init_esm_shims();
+function configUpdateCommand() {
+  const cmd = new Command("config-update");
+  cmd.description("Update codex configuration fields in .fractary/config.yaml").option("--org <slug>", "Update organization slug").option("--project <name>", "Update project name").option("--codex-repo <name>", "Update codex repository name").option("--sync-preset <name>", "Update sync preset (standard, minimal)").option("--no-mcp", "Skip MCP server update").option("--json", "Output as JSON").action(async (options) => {
+    try {
+      const configManager = createConfigManager(process.cwd());
+      const updateOptions = {
+        skipMcp: options.mcp === false
+      };
+      let hasUpdates = false;
+      if (options.org !== void 0) {
+        updateOptions.organization = options.org;
+        hasUpdates = true;
+      }
+      if (options.project !== void 0) {
+        updateOptions.project = options.project;
+        hasUpdates = true;
+      }
+      if (options.codexRepo !== void 0) {
+        updateOptions.codexRepo = options.codexRepo;
+        hasUpdates = true;
+      }
+      if (options.syncPreset !== void 0) {
+        updateOptions.syncPreset = options.syncPreset;
+        hasUpdates = true;
+      }
+      if (!hasUpdates) {
+        if (options.json) {
+          console.log(JSON.stringify({ error: "No fields to update. Provide at least one of: --org, --project, --codex-repo, --sync-preset" }, null, 2));
+        } else {
+          console.error(chalk10.red("Error:"), "No fields to update. Provide at least one of: --org, --project, --codex-repo, --sync-preset");
+        }
+        process.exit(1);
+      }
+      if (!options.json) {
+        console.log(chalk10.blue("Updating codex configuration...\n"));
+      }
+      const result = await configManager.updateCodexSection(updateOptions);
+      if (options.json) {
+        console.log(
+          JSON.stringify(
+            {
+              success: true,
+              configPath: result.configPath,
+              fieldsUpdated: result.fieldsUpdated,
+              mcp: result.mcp
+            },
+            null,
+            2
+          )
+        );
+        return;
+      }
+      if (result.fieldsUpdated.length === 0) {
+        console.log(chalk10.yellow("No fields were updated."));
+        return;
+      }
+      for (const field of result.fieldsUpdated) {
+        console.log(chalk10.green("\u2713"), chalk10.dim(`Updated: ${field}`));
+      }
+      if (result.mcp) {
+        if (result.mcp.alreadyInstalled) {
+          console.log(chalk10.green("\u2713"), chalk10.dim(".mcp.json (already configured)"));
+        } else if (result.mcp.installed) {
+          console.log(chalk10.green("\u2713"), chalk10.dim(".mcp.json (updated)"));
+        }
+      }
+      console.log(chalk10.green("\n\u2713 Codex configuration updated successfully!"));
+    } catch (error) {
+      if (options.json) {
+        console.log(JSON.stringify({ error: error.message }, null, 2));
+      } else {
+        console.error(chalk10.red("Error:"), error.message);
+      }
+      process.exit(1);
+    }
+  });
+  return cmd;
+}
+
+// src/commands/config/validate.ts
+init_esm_shims();
+function configValidateCommand() {
+  const cmd = new Command("config-validate");
+  cmd.description("Validate codex configuration in .fractary/config.yaml (read-only)").option("--json", "Output as JSON").action(async (options) => {
+    try {
+      const configManager = createConfigManager(process.cwd());
+      if (!options.json) {
+        console.log(chalk10.blue("Validating codex configuration...\n"));
+      }
+      const result = await configManager.validateCodexConfig();
+      if (options.json) {
+        console.log(JSON.stringify(result, null, 2));
+        if (!result.valid) {
+          process.exit(1);
+        }
+        return;
+      }
+      if (result.errors.length > 0) {
+        console.log(chalk10.red.bold("Errors:"));
+        for (const error of result.errors) {
+          console.log(chalk10.red("  \u2717"), `${error.field}: ${error.message}`);
+        }
+        console.log();
+      }
+      if (result.warnings.length > 0) {
+        console.log(chalk10.yellow.bold("Warnings:"));
+        for (const warning of result.warnings) {
+          console.log(chalk10.yellow("  \u26A0"), `${warning.field}: ${warning.message}`);
+        }
+        console.log();
+      }
+      if (result.valid) {
+        if (result.warnings.length === 0) {
+          console.log(chalk10.green("\u2713 Codex configuration is valid with no warnings."));
+        } else {
+          console.log(chalk10.green("\u2713 Codex configuration is valid"), chalk10.yellow(`(${result.warnings.length} warning${result.warnings.length > 1 ? "s" : ""})`));
+        }
+      } else {
+        console.log(chalk10.red(`\u2717 Codex configuration is invalid (${result.errors.length} error${result.errors.length > 1 ? "s" : ""})`));
+        process.exit(1);
+      }
+    } catch (error) {
+      if (options.json) {
+        console.log(JSON.stringify({ error: error.message }, null, 2));
+      } else {
+        console.error(chalk10.red("Error:"), error.message);
+      }
+      process.exit(1);
+    }
+  });
+  return cmd;
+}
+
+// src/commands/config/init.ts
+init_esm_shims();
+
 // src/commands/document/index.ts
 init_esm_shims();
 
@@ -1244,14 +545,14 @@ function documentFetchCommand() {
     try {
       const { validateUri } = await import('@fractary/codex');
       if (!validateUri(uri)) {
-        console.error(chalk7.red("Error: Invalid URI format"));
-        console.log(chalk7.dim("Expected: codex://org/project/path/to/file.md"));
-        console.log(chalk7.dim("Example: codex://fractary/codex/docs/api.md"));
+        console.error(chalk10.red("Error: Invalid URI format"));
+        console.log(chalk10.dim("Expected: codex://org/project/path/to/file.md"));
+        console.log(chalk10.dim("Example: codex://fractary/codex/docs/api.md"));
         process.exit(1);
       }
       const client = await getClient();
       if (!options.json && !options.bypassCache) {
-        console.error(chalk7.dim(`Fetching ${uri}...`));
+        console.error(chalk10.dim(`Fetching ${uri}...`));
       }
       const result = await client.fetch(uri, {
         bypassCache: options.bypassCache,
@@ -1271,31 +572,31 @@ function documentFetchCommand() {
         };
         console.log(JSON.stringify(output, null, 2));
       } else if (options.output) {
-        await fs4.writeFile(options.output, result.content);
-        console.log(chalk7.green("\u2713"), `Written to ${options.output}`);
-        console.log(chalk7.dim(`  Size: ${result.content.length} bytes`));
+        await fs2.writeFile(options.output, result.content);
+        console.log(chalk10.green("\u2713"), `Written to ${options.output}`);
+        console.log(chalk10.dim(`  Size: ${result.content.length} bytes`));
         if (result.fromCache) {
-          console.log(chalk7.dim("  Source: cache"));
+          console.log(chalk10.dim("  Source: cache"));
         } else {
-          console.log(chalk7.dim("  Source: storage"));
+          console.log(chalk10.dim("  Source: storage"));
         }
       } else {
         if (result.fromCache && !options.bypassCache) {
-          console.error(chalk7.green("\u2713"), chalk7.dim("from cache\n"));
+          console.error(chalk10.green("\u2713"), chalk10.dim("from cache\n"));
         } else {
-          console.error(chalk7.green("\u2713"), chalk7.dim("fetched\n"));
+          console.error(chalk10.green("\u2713"), chalk10.dim("fetched\n"));
         }
         console.log(result.content.toString("utf-8"));
       }
     } catch (error) {
-      console.error(chalk7.red("Error:"), error.message);
+      console.error(chalk10.red("Error:"), error.message);
       if (error.message.includes("Failed to load configuration")) {
-        console.log(chalk7.dim('\nRun "fractary-codex configure" to create a configuration.'));
+        console.log(chalk10.dim('\nRun "fractary-codex configure" to create a configuration.'));
       } else if (error.message.includes("GITHUB_TOKEN")) {
-        console.log(chalk7.dim('\nSet your GitHub token: export GITHUB_TOKEN="your_token"'));
+        console.log(chalk10.dim('\nSet your GitHub token: export GITHUB_TOKEN="your_token"'));
       } else if (error.message.includes("not found") || error.message.includes("404")) {
-        console.log(chalk7.dim("\nThe document may not exist or you may not have access."));
-        console.log(chalk7.dim("Check the URI and ensure your storage providers are configured correctly."));
+        console.log(chalk10.dim("\nThe document may not exist or you may not have access."));
+        console.log(chalk10.dim("Check the URI and ensure your storage providers are configured correctly."));
       }
       process.exit(1);
     }
@@ -1308,55 +609,116 @@ 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 formatTtl(seconds) {
+  if (seconds < 0) {
+    const expired = -seconds;
+    if (expired < 60) return chalk10.red(`expired ${expired}s ago`);
+    if (expired < 3600) return chalk10.red(`expired ${Math.floor(expired / 60)}m ago`);
+    return chalk10.red(`expired ${Math.floor(expired / 3600)}h ago`);
+  }
+  if (seconds < 60) return chalk10.green(`${seconds}s`);
+  if (seconds < 3600) return chalk10.green(`${Math.floor(seconds / 60)}m`);
+  if (seconds < 86400) return chalk10.yellow(`${Math.floor(seconds / 3600)}h`);
+  return chalk10.dim(`${Math.floor(seconds / 86400)}d`);
+}
+function formatStatus(status) {
+  switch (status) {
+    case "fresh":
+      return chalk10.green("fresh");
+    case "stale":
+      return chalk10.yellow("stale");
+    case "expired":
+      return chalk10.red("expired");
+  }
 }
 function cacheListCommand() {
   const cmd = new Command("cache-list");
-  cmd.description("List cache information").option("--json", "Output as JSON").action(async (options) => {
+  cmd.description("List cache entries").option("--json", "Output as JSON").option("--status <status>", "Filter by status (fresh, stale, expired, all)", "all").option("--limit <n>", "Maximum number of entries to show", parseInt).option("--sort <field>", "Sort by field (uri, size, createdAt, expiresAt)", "uri").option("--desc", "Sort in descending order").option("--verbose", "Show detailed entry information").action(async (options) => {
     try {
       const client = await getClient();
-      const stats = await client.getCacheStats();
-      if (stats.entryCount === 0) {
+      const listOptions = {
+        status: options.status,
+        limit: options.limit,
+        sortBy: options.sort,
+        sortDirection: options.desc ? "desc" : "asc"
+      };
+      const result = await client.listCacheEntries(listOptions);
+      if (result.total === 0) {
         if (options.json) {
-          console.log(JSON.stringify({ entries: 0, message: "Cache is empty" }));
+          console.log(JSON.stringify({ entries: [], total: 0, message: "Cache is empty" }));
         } else {
-          console.log(chalk7.yellow("Cache is empty."));
-          console.log(chalk7.dim("Fetch some documents to populate the cache."));
+          console.log(chalk10.yellow("Cache is empty."));
+          console.log(chalk10.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));
+        console.log(JSON.stringify(result, null, 2));
         return;
       }
-      console.log(chalk7.bold("Cache Overview\n"));
-      console.log(chalk7.bold("Entries:"));
-      console.log(`  Total:    ${chalk7.cyan(stats.entryCount.toString())} entries`);
-      console.log(`  Fresh:    ${chalk7.green(stats.freshCount.toString())} entries`);
-      console.log(`  Stale:    ${stats.staleCount > 0 ? chalk7.yellow(stats.staleCount.toString()) : chalk7.dim("0")} entries`);
-      console.log(`  Expired:  ${stats.expiredCount > 0 ? chalk7.red(stats.expiredCount.toString()) : chalk7.dim("0")} entries`);
-      console.log("");
-      console.log(chalk7.bold("Storage:"));
-      console.log(`  Total size: ${chalk7.cyan(formatSize(stats.totalSize))}`);
-      console.log("");
-      const healthPercent = stats.entryCount > 0 ? stats.freshCount / stats.entryCount * 100 : 100;
-      const healthColor = healthPercent > 80 ? chalk7.green : healthPercent > 50 ? chalk7.yellow : chalk7.red;
-      console.log(`Cache health: ${healthColor(`${healthPercent.toFixed(0)}% fresh`)}`);
+      console.log(chalk10.bold(`Cache Entries (${result.entries.length} of ${result.total})
+`));
+      if (options.verbose) {
+        for (const entry of result.entries) {
+          console.log(chalk10.cyan(entry.uri));
+          console.log(`  Status:       ${formatStatus(entry.status)}`);
+          console.log(`  Size:         ${formatBytes(entry.size)}`);
+          console.log(`  Content-Type: ${chalk10.dim(entry.contentType)}`);
+          console.log(`  TTL:          ${formatTtl(entry.remainingTtl)}`);
+          console.log(`  In Memory:    ${entry.inMemory ? chalk10.green("yes") : chalk10.dim("no")}`);
+          console.log("");
+        }
+      } else {
+        const maxUriLen = Math.min(
+          60,
+          Math.max(...result.entries.map((e) => e.uri.length))
+        );
+        console.log(
+          chalk10.dim(
+            `${"URI".padEnd(maxUriLen)}  ${"STATUS".padEnd(8)}  ${"SIZE".padEnd(10)}  TTL`
+          )
+        );
+        console.log(chalk10.dim("\u2500".repeat(maxUriLen + 35)));
+        for (const entry of result.entries) {
+          const uri = entry.uri.length > maxUriLen ? "..." + entry.uri.slice(-(maxUriLen - 3)) : entry.uri.padEnd(maxUriLen);
+          console.log(
+            `${chalk10.cyan(uri)}  ${formatStatus(entry.status).padEnd(17)}  ${formatBytes(entry.size).padEnd(10)}  ${formatTtl(entry.remainingTtl)}`
+          );
+        }
+      }
+      if (result.hasMore) {
+        console.log("");
+        console.log(
+          chalk10.dim(
+            `Showing ${result.entries.length} of ${result.total} entries. Use --limit to see more.`
+          )
+        );
+      }
+      const stats = await client.getCacheStats();
       console.log("");
-      console.log(chalk7.dim("Note: Individual cache entries are managed by the SDK."));
-      console.log(chalk7.dim('Use "fractary-codex cache-stats" for detailed statistics.'));
-      console.log(chalk7.dim('Use "fractary-codex cache-clear" to clear cache entries.'));
+      console.log(chalk10.dim("\u2500".repeat(60)));
+      console.log(
+        chalk10.dim(
+          `Total: ${stats.entryCount} entries (${formatBytes(stats.totalSize)}) | ${stats.freshCount} fresh, ${stats.staleCount} stale, ${stats.expiredCount} expired`
+        )
+      );
     } catch (error) {
-      console.error(chalk7.red("Error:"), error.message);
+      const errorMessage = error.message || "Unknown error";
+      if (errorMessage.includes("ENOENT") || errorMessage.includes("not found")) {
+        console.error(chalk10.red("Error:"), "Cache directory not accessible");
+        console.error(chalk10.dim('Run "fractary-codex configure" to initialize the cache.'));
+      } else if (errorMessage.includes("EACCES") || errorMessage.includes("permission")) {
+        console.error(chalk10.red("Error:"), "Permission denied accessing cache directory");
+        console.error(chalk10.dim("Check file permissions for .fractary/codex/cache/"));
+      } else if (errorMessage.includes("ENOSPC")) {
+        console.error(chalk10.red("Error:"), "No space left on device");
+        console.error(chalk10.dim("Free up disk space and try again."));
+      } else if (errorMessage.includes("parse") || errorMessage.includes("JSON")) {
+        console.error(chalk10.red("Error:"), "Failed to parse cache metadata");
+        console.error(chalk10.dim('The cache may be corrupted. Try "fractary-codex cache-clear".'));
+      } else {
+        console.error(chalk10.red("Error:"), errorMessage);
+      }
       process.exit(1);
     }
   });
@@ -1372,7 +734,7 @@ function cacheClearCommand() {
       const client = await getClient();
       const statsBefore = await client.getCacheStats();
       if (statsBefore.entryCount === 0) {
-        console.log(chalk7.yellow("Cache is already empty. Nothing to clear."));
+        console.log(chalk10.yellow("Cache is already empty. Nothing to clear."));
         return;
       }
       let pattern;
@@ -1381,63 +743,53 @@ function cacheClearCommand() {
       } else if (options.pattern) {
         pattern = options.pattern;
       } else {
-        console.log(chalk7.yellow("Please specify what to clear:"));
-        console.log(chalk7.dim("  --all        Clear entire cache"));
-        console.log(chalk7.dim('  --pattern    Clear entries matching pattern (e.g., "codex://fractary/*")'));
+        console.log(chalk10.yellow("Please specify what to clear:"));
+        console.log(chalk10.dim("  --all        Clear entire cache"));
+        console.log(chalk10.dim('  --pattern    Clear entries matching pattern (e.g., "codex://fractary/*")'));
         console.log("");
-        console.log(chalk7.dim("Examples:"));
-        console.log(chalk7.dim("  fractary-codex cache-clear --all"));
-        console.log(chalk7.dim('  fractary-codex cache-clear --pattern "codex://fractary/cli/*"'));
+        console.log(chalk10.dim("Examples:"));
+        console.log(chalk10.dim("  fractary-codex cache-clear --all"));
+        console.log(chalk10.dim('  fractary-codex cache-clear --pattern "codex://fractary/cli/*"'));
         return;
       }
       if (options.dryRun) {
-        console.log(chalk7.blue("Dry run - would clear:\n"));
+        console.log(chalk10.blue("Dry run - would clear:\n"));
         if (pattern) {
-          console.log(chalk7.dim(`  Pattern: ${pattern}`));
-          console.log(chalk7.dim(`  This would invalidate matching cache entries`));
+          console.log(chalk10.dim(`  Pattern: ${pattern}`));
+          console.log(chalk10.dim(`  This would invalidate matching cache entries`));
         } else {
-          console.log(chalk7.dim(`  All cache entries (${statsBefore.entryCount} entries)`));
+          console.log(chalk10.dim(`  All cache entries (${statsBefore.entryCount} entries)`));
         }
-        console.log(chalk7.dim(`
-Total size: ${formatSize2(statsBefore.totalSize)}`));
+        console.log(chalk10.dim(`
+Total size: ${formatBytes(statsBefore.totalSize)}`));
         return;
       }
       if (pattern) {
-        console.log(chalk7.blue(`Clearing cache entries matching pattern: ${pattern}
+        console.log(chalk10.blue(`Clearing cache entries matching pattern: ${pattern}
 `));
         await client.invalidateCache(pattern);
       } else {
-        console.log(chalk7.blue(`Clearing entire cache (${statsBefore.entryCount} entries)...
+        console.log(chalk10.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(chalk7.green(`\u2713 Cleared ${entriesCleared} entries (${formatSize2(sizeFreed)} freed)`));
+      console.log(chalk10.green(`\u2713 Cleared ${entriesCleared} entries (${formatBytes(sizeFreed)} freed)`));
       if (statsAfter.entryCount > 0) {
-        console.log(chalk7.dim(`  Remaining: ${statsAfter.entryCount} entries (${formatSize2(statsAfter.totalSize)})`));
+        console.log(chalk10.dim(`  Remaining: ${statsAfter.entryCount} entries (${formatBytes(statsAfter.totalSize)})`));
       }
     } catch (error) {
-      console.error(chalk7.red("Error:"), error.message);
+      console.error(chalk10.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("cache-stats");
   cmd.description("Display cache statistics").option("--json", "Output as JSON").action(async (options) => {
@@ -1448,25 +800,25 @@ function cacheStatsCommand() {
         console.log(JSON.stringify(stats, null, 2));
         return;
       }
-      console.log(chalk7.bold("Cache Statistics\n"));
-      console.log(chalk7.bold("Overview"));
-      console.log(`  Total entries:     ${chalk7.cyan(stats.entryCount.toString())}`);
-      console.log(`  Total size:        ${chalk7.cyan(formatSize3(stats.totalSize))}`);
-      console.log(`  Fresh entries:     ${chalk7.green(stats.freshCount.toString())}`);
-      console.log(`  Stale entries:     ${stats.staleCount > 0 ? chalk7.yellow(stats.staleCount.toString()) : chalk7.dim("0")}`);
-      console.log(`  Expired entries:   ${stats.expiredCount > 0 ? chalk7.red(stats.expiredCount.toString()) : chalk7.dim("0")}`);
+      console.log(chalk10.bold("Cache Statistics\n"));
+      console.log(chalk10.bold("Overview"));
+      console.log(`  Total entries:     ${chalk10.cyan(stats.entryCount.toString())}`);
+      console.log(`  Total size:        ${chalk10.cyan(formatBytes(stats.totalSize))}`);
+      console.log(`  Fresh entries:     ${chalk10.green(stats.freshCount.toString())}`);
+      console.log(`  Stale entries:     ${stats.staleCount > 0 ? chalk10.yellow(stats.staleCount.toString()) : chalk10.dim("0")}`);
+      console.log(`  Expired entries:   ${stats.expiredCount > 0 ? chalk10.red(stats.expiredCount.toString()) : chalk10.dim("0")}`);
       console.log("");
       const healthPercent = stats.entryCount > 0 ? stats.freshCount / stats.entryCount * 100 : 100;
-      const healthColor = healthPercent > 80 ? chalk7.green : healthPercent > 50 ? chalk7.yellow : chalk7.red;
+      const healthColor = healthPercent > 80 ? chalk10.green : healthPercent > 50 ? chalk10.yellow : chalk10.red;
       console.log(`Cache health: ${healthColor(`${healthPercent.toFixed(0)}% fresh`)}`);
       if (stats.expiredCount > 0) {
-        console.log(chalk7.dim('\nRun "fractary-codex cache-clear --pattern <pattern>" to clean up entries.'));
+        console.log(chalk10.dim('\nRun "fractary-codex cache-clear --pattern <pattern>" to clean up entries.'));
       }
       if (stats.entryCount === 0) {
-        console.log(chalk7.dim("\nNo cached entries. Fetch some documents to populate the cache."));
+        console.log(chalk10.dim("\nNo cached entries. Fetch some documents to populate the cache."));
       }
     } catch (error) {
-      console.error(chalk7.red("Error:"), error.message);
+      console.error(chalk10.red("Error:"), error.message);
       process.exit(1);
     }
   });
@@ -1475,239 +827,81 @@ function cacheStatsCommand() {
 
 // src/commands/cache/health.ts
 init_esm_shims();
-init_migrate_config();
-async function fileExists2(filePath) {
-  try {
-    await fs4.access(filePath);
-    return true;
-  } catch {
-    return false;
-  }
-}
-async function checkConfiguration() {
-  const configPath = path3.join(process.cwd(), ".fractary", "config.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: "Migration from legacy JSON format may be required"
-        };
-      }
-      return {
-        name: "Configuration",
-        status: "fail",
-        message: "No configuration found",
-        details: 'Run "fractary-codex configure" to create configuration'
-      };
-    }
-    const config = await readCodexConfig(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", "config.yaml");
-  try {
-    const config = await readCodexConfig(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/config.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 cacheHealthCommand() {
   const cmd = new Command("cache-health");
   cmd.description("Run diagnostics on codex setup").option("--json", "Output as JSON").action(async (options) => {
     try {
+      const healthChecker = createHealthChecker({
+        projectRoot: process.cwd()
+      });
       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;
+      checks.push(await healthChecker.checkConfiguration());
+      checks.push(await healthChecker.checkStorage());
+      try {
+        const client = await getClient();
+        const organization = client.getOrganization();
+        checks.push({
+          name: "SDK Client",
+          status: "pass",
+          message: "CodexClient initialized successfully",
+          details: `Organization: ${organization}`
+        });
+        const cacheStats = await client.getCacheStats();
+        checks.push(healthChecker.checkCacheFromStats(cacheStats));
+        const registry = client.getTypeRegistry();
+        checks.push(healthChecker.checkTypesFromRegistry(registry));
+      } catch (error) {
+        checks.push({
+          name: "SDK Client",
+          status: "fail",
+          message: "Failed to initialize CodexClient",
+          details: error.message
+        });
+        checks.push({
+          name: "Cache",
+          status: "warn",
+          message: "Cache check skipped",
+          details: "SDK client not available"
+        });
+        checks.push({
+          name: "Type Registry",
+          status: "warn",
+          message: "Type registry check skipped",
+          details: "SDK client not available"
+        });
+      }
+      const result = healthChecker.summarize(checks);
       if (options.json) {
-        console.log(JSON.stringify({
-          summary: {
-            total: checks.length,
-            passed,
-            warned,
-            failed,
-            healthy: failed === 0
-          },
-          checks
-        }, null, 2));
+        console.log(JSON.stringify(result, null, 2));
         return;
       }
-      console.log(chalk7.bold("Codex Health Check\n"));
-      for (const check of checks) {
-        const icon = check.status === "pass" ? chalk7.green("\u2713") : check.status === "warn" ? chalk7.yellow("\u26A0") : chalk7.red("\u2717");
-        const statusColor = check.status === "pass" ? chalk7.green : check.status === "warn" ? chalk7.yellow : chalk7.red;
-        console.log(`${icon} ${chalk7.bold(check.name)}`);
+      console.log(chalk10.bold("Codex Health Check\n"));
+      for (const check of result.checks) {
+        const icon = check.status === "pass" ? chalk10.green("\u2713") : check.status === "warn" ? chalk10.yellow("\u26A0") : chalk10.red("\u2717");
+        const statusColor = check.status === "pass" ? chalk10.green : check.status === "warn" ? chalk10.yellow : chalk10.red;
+        console.log(`${icon} ${chalk10.bold(check.name)}`);
         console.log(`  ${statusColor(check.message)}`);
         if (check.details) {
-          console.log(`  ${chalk7.dim(check.details)}`);
+          console.log(`  ${chalk10.dim(check.details)}`);
         }
         console.log("");
       }
-      console.log(chalk7.dim("\u2500".repeat(60)));
-      const overallStatus = failed > 0 ? chalk7.red("UNHEALTHY") : warned > 0 ? chalk7.yellow("DEGRADED") : chalk7.green("HEALTHY");
+      console.log(chalk10.dim("\u2500".repeat(60)));
+      const overallStatus = result.summary.status === "unhealthy" ? chalk10.red("UNHEALTHY") : result.summary.status === "degraded" ? chalk10.yellow("DEGRADED") : chalk10.green("HEALTHY");
       console.log(`Status: ${overallStatus}`);
-      console.log(chalk7.dim(`${passed} passed, ${warned} warnings, ${failed} failed`));
-      if (failed > 0 || warned > 0) {
+      console.log(
+        chalk10.dim(`${result.summary.passed} passed, ${result.summary.warned} warnings, ${result.summary.failed} failed`)
+      );
+      if (result.summary.failed > 0 || result.summary.warned > 0) {
         console.log("");
-        console.log(chalk7.dim("Run checks individually for more details:"));
-        console.log(chalk7.dim("  fractary-codex cache-stats"));
+        console.log(chalk10.dim("Run checks individually for more details:"));
+        console.log(chalk10.dim("  fractary-codex cache-stats"));
       }
-      if (failed > 0) {
+      if (result.summary.failed > 0) {
         process.exit(1);
       }
     } catch (error) {
-      console.error(chalk7.red("Error:"), error.message);
+      console.error(chalk10.red("Error:"), error.message);
       process.exit(1);
     }
   });
@@ -1716,7 +910,11 @@ function cacheHealthCommand() {
 
 // src/commands/sync.ts
 init_esm_shims();
-init_migrate_config();
+
+// src/config/migrate-config.ts
+init_esm_shims();
+
+// src/commands/sync.ts
 function getEnvironmentBranch(config, env) {
   const envMap = config.sync?.environments || {
     dev: "develop",
@@ -1726,26 +924,17 @@ function getEnvironmentBranch(config, env) {
   };
   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 syncCommand() {
   const cmd = new Command("sync");
   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").option("--work-id <id>", "GitHub issue number or URL to scope sync to").action(async (name, options) => {
     try {
-      const configPath = path3.join(process.cwd(), ".fractary", "config.yaml");
+      const configPath = path4.join(process.cwd(), ".fractary", "config.yaml");
       let config;
       try {
         config = await readCodexConfig(configPath);
       } catch (error) {
-        console.error(chalk7.red("Error:"), "Codex not initialized.");
-        console.log(chalk7.dim('Run "fractary-codex configure" first.'));
+        console.error(chalk10.red("Error:"), "Codex not initialized.");
+        console.log(chalk10.dim('Run "fractary-codex configure" first.'));
         process.exit(1);
       }
       const { createSyncManager, createLocalStorage, detectCurrentProject } = await import('@fractary/codex');
@@ -1758,14 +947,14 @@ function syncCommand() {
         projectName = detected.project || void 0;
       }
       if (!projectName) {
-        console.error(chalk7.red("Error:"), "Could not determine project name.");
-        console.log(chalk7.dim("Provide project name as argument, set codex.project in config, or run from a git repository."));
+        console.error(chalk10.red("Error:"), "Could not determine project name.");
+        console.log(chalk10.dim("Provide project name as argument, set codex.project in config, or run from a git repository."));
         process.exit(1);
       }
       const validDirections = ["to-codex", "from-codex", "bidirectional"];
       if (!validDirections.includes(options.direction)) {
-        console.error(chalk7.red("Error:"), `Invalid direction: ${options.direction}`);
-        console.log(chalk7.dim("Valid options: to-codex, from-codex, bidirectional"));
+        console.error(chalk10.red("Error:"), `Invalid direction: ${options.direction}`);
+        console.log(chalk10.dim("Valid options: to-codex, from-codex, bidirectional"));
         process.exit(1);
       }
       const direction = options.direction;
@@ -1776,7 +965,7 @@ function syncCommand() {
       const syncManager = createSyncManager({
         localStorage,
         config: config.sync,
-        manifestPath: path3.join(process.cwd(), ".fractary", ".codex-sync-manifest.json")
+        manifestPath: path4.join(process.cwd(), ".fractary", ".codex-sync-manifest.json")
       });
       const defaultToCodexPatterns = [
         "docs/**/*.md",
@@ -1806,13 +995,13 @@ function syncCommand() {
           });
           matches.forEach((match) => matchedFilePaths.add(match));
         } catch (error) {
-          console.error(chalk7.yellow(`Warning: Invalid pattern "${pattern}": ${error.message}`));
+          console.error(chalk10.yellow(`Warning: Invalid pattern "${pattern}": ${error.message}`));
         }
       }
       const targetFiles = await Promise.all(
         Array.from(matchedFilePaths).map(async (filePath) => {
-          const fullPath = path3.join(sourceDir, filePath);
-          const stats = await import('fs/promises').then((fs8) => fs8.stat(fullPath));
+          const fullPath = path4.join(sourceDir, filePath);
+          const stats = await import('fs/promises').then((fs3) => fs3.stat(fullPath));
           return {
             path: filePath,
             size: stats.size,
@@ -1836,14 +1025,14 @@ function syncCommand() {
         try {
           const { ensureCodexCloned: ensureCodexCloned2 } = await Promise.resolve().then(() => (init_codex_repository(), codex_repository_exports));
           if (!options.json) {
-            console.log(chalk7.blue("\u2139 Cloning/updating codex repository..."));
+            console.log(chalk10.blue("\u2139 Cloning/updating codex repository..."));
           }
           codexRepoPath = await ensureCodexCloned2(config, {
             branch: targetBranch
           });
           if (!options.json) {
-            console.log(chalk7.dim(`  Codex cloned to: ${codexRepoPath}`));
-            console.log(chalk7.dim("  Scanning for files routing to this project...\n"));
+            console.log(chalk10.dim(`  Codex cloned to: ${codexRepoPath}`));
+            console.log(chalk10.dim("  Scanning for files routing to this project...\n"));
           } else {
             console.log(JSON.stringify({
               info: "Routing-aware sync: cloned codex repository and scanning for files targeting this project",
@@ -1851,29 +1040,29 @@ function syncCommand() {
             }, null, 2));
           }
         } catch (error) {
-          console.error(chalk7.red("Error:"), "Failed to clone codex repository");
-          console.error(chalk7.dim(`  ${error.message}`));
-          console.log(chalk7.yellow("\nTroubleshooting:"));
+          console.error(chalk10.red("Error:"), "Failed to clone codex repository");
+          console.error(chalk10.dim(`  ${error.message}`));
+          console.log(chalk10.yellow("\nTroubleshooting:"));
           if (error.message.includes("Git command not found")) {
-            console.log(chalk7.dim("  Git is not installed or not in PATH."));
-            console.log(chalk7.dim("  Install git: https://git-scm.com/downloads"));
+            console.log(chalk10.dim("  Git is not installed or not in PATH."));
+            console.log(chalk10.dim("  Install git: https://git-scm.com/downloads"));
           } else if (error.message.includes("authentication failed") || error.message.includes("Authentication failed")) {
-            console.log(chalk7.dim("  GitHub authentication is required for private repositories."));
-            console.log(chalk7.dim("  1. Check auth status: gh auth status"));
-            console.log(chalk7.dim("  2. Login if needed: gh auth login"));
-            console.log(chalk7.dim("  3. Or set GITHUB_TOKEN environment variable"));
+            console.log(chalk10.dim("  GitHub authentication is required for private repositories."));
+            console.log(chalk10.dim("  1. Check auth status: gh auth status"));
+            console.log(chalk10.dim("  2. Login if needed: gh auth login"));
+            console.log(chalk10.dim("  3. Or set GITHUB_TOKEN environment variable"));
           } else if (error.message.includes("Permission denied")) {
-            console.log(chalk7.dim("  Permission denied accessing repository files."));
-            console.log(chalk7.dim("  1. Check file/directory permissions"));
-            console.log(chalk7.dim("  2. Ensure you have access to the repository"));
+            console.log(chalk10.dim("  Permission denied accessing repository files."));
+            console.log(chalk10.dim("  1. Check file/directory permissions"));
+            console.log(chalk10.dim("  2. Ensure you have access to the repository"));
           } else if (error.message.includes("not found") || error.message.includes("does not exist")) {
-            console.log(chalk7.dim(`  Repository not found: ${config.organization}/${config.codex_repo || "codex"}`));
-            console.log(chalk7.dim("  1. Verify the repository exists on GitHub"));
-            console.log(chalk7.dim("  2. Check organization and repository names in config"));
+            console.log(chalk10.dim(`  Repository not found: ${config.organization}/${config.codex_repo || "codex"}`));
+            console.log(chalk10.dim("  1. Verify the repository exists on GitHub"));
+            console.log(chalk10.dim("  2. Check organization and repository names in config"));
           } else {
-            console.log(chalk7.dim("  1. Ensure git is installed: git --version"));
-            console.log(chalk7.dim("  2. Check GitHub auth: gh auth status"));
-            console.log(chalk7.dim(`  3. Verify repo exists: ${config.organization}/${config.codex_repo || "codex"}`));
+            console.log(chalk10.dim("  1. Ensure git is installed: git --version"));
+            console.log(chalk10.dim("  2. Check GitHub auth: gh auth status"));
+            console.log(chalk10.dim(`  3. Verify repo exists: ${config.organization}/${config.codex_repo || "codex"}`));
           }
           process.exit(1);
         }
@@ -1892,17 +1081,17 @@ function syncCommand() {
         try {
           const { ensureCodexCloned: ensureCodexCloned2 } = await Promise.resolve().then(() => (init_codex_repository(), codex_repository_exports));
           if (!options.json) {
-            console.log(chalk7.blue("\u2139 Cloning/updating codex repository..."));
+            console.log(chalk10.blue("\u2139 Cloning/updating codex repository..."));
           }
           codexRepoPath = await ensureCodexCloned2(config, {
             branch: targetBranch
           });
           if (!options.json) {
-            console.log(chalk7.dim(`  Codex cloned to: ${codexRepoPath}`));
+            console.log(chalk10.dim(`  Codex cloned to: ${codexRepoPath}`));
           }
         } catch (error) {
-          console.error(chalk7.red("Error:"), "Failed to clone codex repository");
-          console.error(chalk7.dim(`  ${error.message}`));
+          console.error(chalk10.red("Error:"), "Failed to clone codex repository");
+          console.error(chalk10.dim(`  ${error.message}`));
           process.exit(1);
         }
         plan = await syncManager.createPlan(
@@ -1914,7 +1103,7 @@ function syncCommand() {
           syncOptions
         );
         plan.source = sourceDir;
-        plan.target = path3.join(codexRepoPath, "projects", projectName);
+        plan.target = path4.join(codexRepoPath, "projects", projectName);
       }
       if (plan.totalFiles === 0) {
         if (options.json) {
@@ -1928,7 +1117,7 @@ function syncCommand() {
             message: "No files to sync"
           }, null, 2));
         } else {
-          console.log(chalk7.yellow("No files to sync."));
+          console.log(chalk10.yellow("No files to sync."));
         }
         return;
       }
@@ -1984,81 +1173,81 @@ function syncCommand() {
         }, null, 2));
         return;
       }
-      console.log(chalk7.bold("Sync Plan\n"));
-      console.log(`  Project:      ${chalk7.cyan(projectName)}`);
-      console.log(`  Organization: ${chalk7.cyan(config.organization)}`);
-      console.log(`  Environment:  ${chalk7.cyan(options.env)} (${targetBranch})`);
-      console.log(`  Direction:    ${chalk7.cyan(direction)}`);
-      console.log(`  Files:        ${chalk7.cyan(plan.totalFiles.toString())}`);
-      console.log(`  Total size:   ${chalk7.cyan(formatBytes(plan.totalBytes))}`);
+      console.log(chalk10.bold("Sync Plan\n"));
+      console.log(`  Project:      ${chalk10.cyan(projectName)}`);
+      console.log(`  Organization: ${chalk10.cyan(config.organization)}`);
+      console.log(`  Environment:  ${chalk10.cyan(options.env)} (${targetBranch})`);
+      console.log(`  Direction:    ${chalk10.cyan(direction)}`);
+      console.log(`  Files:        ${chalk10.cyan(plan.totalFiles.toString())}`);
+      console.log(`  Total size:   ${chalk10.cyan(formatBytes(plan.totalBytes))}`);
       if (plan.estimatedTime) {
-        console.log(`  Est. time:    ${chalk7.dim(formatDuration(plan.estimatedTime))}`);
+        console.log(`  Est. time:    ${chalk10.dim(formatDuration(plan.estimatedTime))}`);
       }
       if (routingScan) {
         console.log("");
-        console.log(chalk7.bold("Routing Statistics\n"));
-        console.log(`  Scanned:      ${chalk7.cyan(routingScan.stats.totalScanned.toString())} files`);
-        console.log(`  Matched:      ${chalk7.cyan(routingScan.stats.totalMatched.toString())} files`);
-        console.log(`  Source projects: ${chalk7.cyan(routingScan.stats.sourceProjects.length.toString())}`);
+        console.log(chalk10.bold("Routing Statistics\n"));
+        console.log(`  Scanned:      ${chalk10.cyan(routingScan.stats.totalScanned.toString())} files`);
+        console.log(`  Matched:      ${chalk10.cyan(routingScan.stats.totalMatched.toString())} files`);
+        console.log(`  Source projects: ${chalk10.cyan(routingScan.stats.sourceProjects.length.toString())}`);
         if (routingScan.stats.sourceProjects.length > 0) {
-          console.log(chalk7.dim(`    ${routingScan.stats.sourceProjects.slice(0, 5).join(", ")}`));
+          console.log(chalk10.dim(`    ${routingScan.stats.sourceProjects.slice(0, 5).join(", ")}`));
           if (routingScan.stats.sourceProjects.length > 5) {
-            console.log(chalk7.dim(`    ... and ${routingScan.stats.sourceProjects.length - 5} more`));
+            console.log(chalk10.dim(`    ... and ${routingScan.stats.sourceProjects.length - 5} more`));
           }
         }
-        console.log(`  Scan time:    ${chalk7.dim(formatDuration(routingScan.stats.durationMs))}`);
+        console.log(`  Scan time:    ${chalk10.dim(formatDuration(routingScan.stats.durationMs))}`);
       }
       console.log("");
       if (plan.conflicts.length > 0) {
-        console.log(chalk7.yellow(`\u26A0 ${plan.conflicts.length} conflicts detected:`));
+        console.log(chalk10.yellow(`\u26A0 ${plan.conflicts.length} conflicts detected:`));
         for (const conflict of plan.conflicts.slice(0, 5)) {
-          console.log(chalk7.yellow(`  \u2022 ${conflict.path}`));
+          console.log(chalk10.yellow(`  \u2022 ${conflict.path}`));
         }
         if (plan.conflicts.length > 5) {
-          console.log(chalk7.dim(`  ... and ${plan.conflicts.length - 5} more`));
+          console.log(chalk10.dim(`  ... and ${plan.conflicts.length - 5} more`));
         }
         console.log("");
       }
       if (plan.skipped.length > 0) {
-        console.log(chalk7.dim(`${plan.skipped.length} files skipped (no changes)`));
+        console.log(chalk10.dim(`${plan.skipped.length} files skipped (no changes)`));
         console.log("");
       }
       if (options.dryRun) {
-        console.log(chalk7.blue("Dry run - would sync:\n"));
+        console.log(chalk10.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" ? chalk7.green : file.operation === "update" ? chalk7.yellow : chalk7.dim;
+          const opColor = file.operation === "create" ? chalk10.green : file.operation === "update" ? chalk10.yellow : chalk10.dim;
           console.log(
-            chalk7.dim(`  ${arrow}`),
+            chalk10.dim(`  ${arrow}`),
             opColor(file.operation.padEnd(7)),
             file.path,
-            chalk7.dim(`(${formatBytes(file.size || 0)})`)
+            chalk10.dim(`(${formatBytes(file.size || 0)})`)
           );
         }
         if (plan.files.length > 10) {
-          console.log(chalk7.dim(`  ... and ${plan.files.length - 10} more files`));
+          console.log(chalk10.dim(`  ... and ${plan.files.length - 10} more files`));
         }
-        console.log(chalk7.dim(`
+        console.log(chalk10.dim(`
 Total: ${plan.totalFiles} files (${formatBytes(plan.totalBytes)})`));
-        console.log(chalk7.dim("Run without --dry-run to execute sync."));
+        console.log(chalk10.dim("Run without --dry-run to execute sync."));
         return;
       }
-      console.log(chalk7.blue("Syncing...\n"));
+      console.log(chalk10.blue("Syncing...\n"));
       const startTime = Date.now();
       const result = await syncManager.executePlan(plan, syncOptions);
       const duration = Date.now() - startTime;
       if (direction === "to-codex" && codexRepoPath && result.synced > 0) {
         try {
           if (!options.json) {
-            console.log(chalk7.blue("Committing and pushing to codex..."));
+            console.log(chalk10.blue("Committing and pushing to codex..."));
           }
           const { RepoManager } = await import('@fractary/core/repo');
           const repoManager = new RepoManager({ platform: "github" }, codexRepoPath);
           repoManager.stageAll();
           if (repoManager.isClean()) {
             if (!options.json) {
-              console.log(chalk7.dim("  No changes to push - codex is already up to date"));
+              console.log(chalk10.dim("  No changes to push - codex is already up to date"));
             }
           } else {
             repoManager.commit({
@@ -2066,41 +1255,41 @@ Total: ${plan.totalFiles} files (${formatBytes(plan.totalBytes)})`));
             });
             repoManager.push({});
             if (!options.json) {
-              console.log(chalk7.dim("  Changes pushed to codex repository"));
+              console.log(chalk10.dim("  Changes pushed to codex repository"));
             }
           }
         } catch (error) {
-          console.error(chalk7.red("Error pushing to codex:"), error.message);
+          console.error(chalk10.red("Error pushing to codex:"), error.message);
         }
       }
       console.log("");
       if (result.success) {
-        console.log(chalk7.green(`\u2713 Sync completed successfully`));
-        console.log(chalk7.dim(`  Synced: ${result.synced} files`));
+        console.log(chalk10.green(`\u2713 Sync completed successfully`));
+        console.log(chalk10.dim(`  Synced: ${result.synced} files`));
         if (result.skipped > 0) {
-          console.log(chalk7.dim(`  Skipped: ${result.skipped} files`));
+          console.log(chalk10.dim(`  Skipped: ${result.skipped} files`));
         }
-        console.log(chalk7.dim(`  Duration: ${formatDuration(duration)}`));
+        console.log(chalk10.dim(`  Duration: ${formatDuration(duration)}`));
       } else {
-        console.log(chalk7.yellow(`\u26A0 Sync completed with errors`));
-        console.log(chalk7.green(`  Synced: ${result.synced} files`));
-        console.log(chalk7.red(`  Failed: ${result.failed} files`));
+        console.log(chalk10.yellow(`\u26A0 Sync completed with errors`));
+        console.log(chalk10.green(`  Synced: ${result.synced} files`));
+        console.log(chalk10.red(`  Failed: ${result.failed} files`));
         if (result.skipped > 0) {
-          console.log(chalk7.dim(`  Skipped: ${result.skipped} files`));
+          console.log(chalk10.dim(`  Skipped: ${result.skipped} files`));
         }
         if (result.errors.length > 0) {
           console.log("");
-          console.log(chalk7.red("Errors:"));
+          console.log(chalk10.red("Errors:"));
           for (const error of result.errors.slice(0, 5)) {
-            console.log(chalk7.red(`  \u2022 ${error.path}: ${error.error}`));
+            console.log(chalk10.red(`  \u2022 ${error.path}: ${error.error}`));
           }
           if (result.errors.length > 5) {
-            console.log(chalk7.dim(`  ... and ${result.errors.length - 5} more errors`));
+            console.log(chalk10.dim(`  ... and ${result.errors.length - 5} more errors`));
           }
         }
       }
     } catch (error) {
-      console.error(chalk7.red("Error:"), error.message);
+      console.error(chalk10.red("Error:"), error.message);
       process.exit(1);
     }
   });
@@ -2113,7 +1302,9 @@ var VERSION = packageJson.version;
 function createCLI() {
   const program = new Command("fractary-codex");
   program.description("Centralized knowledge management and distribution for AI agents").version(VERSION);
-  program.addCommand(configureCommand());
+  program.addCommand(configInitializeCommand());
+  program.addCommand(configUpdateCommand());
+  program.addCommand(configValidateCommand());
   program.addCommand(documentFetchCommand());
   program.addCommand(cacheListCommand());
   program.addCommand(cacheClearCommand());