@traits-dev/cli 0.1.0

package/dist/traits.js

@@ -0,0 +1,1501 @@
+#!/usr/bin/env node
+
+// src/bin/traits.ts
+import fs4 from "fs";
+import path6 from "path";
+import { fileURLToPath } from "url";
+
+// src/commands/compile.ts
+import path from "path";
+import { compileProfile } from "@traits-dev/core";
+import {
+  formatValidationResult,
+  toValidationResultObject
+} from "@traits-dev/core/internal";
+function printCompileUsage(out = process.stderr) {
+  out.write(
+    [
+      "Usage:",
+      "  traits compile <profile-path> --model <model> [options]",
+      "",
+      "Options:",
+      "  --model <model>           Model target (required)",
+      "  --json                    Output structured JSON",
+      "  --strict                  Treat warnings as compile-blocking",
+      "  --explain                 Include compilation trace output",
+      "  --context key=value       Activate context adaptation (repeatable)",
+      "  --knowledge-base-dir      Directory containing compiler pattern files",
+      "  --bundled-profiles-dir    Directory for bundled starter profiles",
+      "  --verbose                 Include additional command metadata",
+      "  --no-color                Disable colorized output",
+      ""
+    ].join("\n")
+  );
+}
+function parseContextArg(value) {
+  const [key, rawValue] = String(value).split("=", 2);
+  const normalizedKey = String(key).trim();
+  if (!normalizedKey) return { error: `Invalid context value "${value}"` };
+  if (rawValue == null) return { key: normalizedKey, value: true };
+  const normalizedValue = String(rawValue).trim().toLowerCase();
+  if (normalizedValue === "true" || normalizedValue === "1") {
+    return { key: normalizedKey, value: true };
+  }
+  if (normalizedValue === "false" || normalizedValue === "0") {
+    return { key: normalizedKey, value: false };
+  }
+  return { key: normalizedKey, value: rawValue };
+}
+function parseCompileArgs(args) {
+  const result = {
+    profilePath: null,
+    model: null,
+    strict: false,
+    json: false,
+    explain: false,
+    verbose: false,
+    noColor: false,
+    knowledgeBaseDir: null,
+    bundledProfilesDir: null,
+    context: {}
+  };
+  const positionals = [];
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "--strict") {
+      result.strict = true;
+      continue;
+    }
+    if (arg === "--json") {
+      result.json = true;
+      continue;
+    }
+    if (arg === "--explain") {
+      result.explain = true;
+      continue;
+    }
+    if (arg === "--verbose") {
+      result.verbose = true;
+      continue;
+    }
+    if (arg === "--no-color") {
+      result.noColor = true;
+      continue;
+    }
+    if (arg === "--model" || arg === "--bundled-profiles-dir" || arg === "--context" || arg === "--knowledge-base-dir") {
+      const value = args[index + 1];
+      if (!value) return { error: `Missing value for "${arg}"` };
+      if (arg === "--model") {
+        result.model = value;
+      } else if (arg === "--bundled-profiles-dir") {
+        result.bundledProfilesDir = value;
+      } else if (arg === "--knowledge-base-dir") {
+        result.knowledgeBaseDir = value;
+      } else {
+        const parsedContext = parseContextArg(value);
+        if ("error" in parsedContext) return { error: parsedContext.error };
+        result.context[parsedContext.key] = parsedContext.value;
+      }
+      index += 1;
+      continue;
+    }
+    if (arg.startsWith("--")) {
+      return { error: `Unknown option "${arg}"` };
+    }
+    positionals.push(arg);
+  }
+  if (positionals.length !== 1) {
+    return { error: "Expected exactly one profile path argument" };
+  }
+  result.profilePath = positionals[0];
+  if (!result.model) {
+    return { error: 'Missing required option "--model"' };
+  }
+  return { value: result };
+}
+function runCompile(args, io = process) {
+  const parsed = parseCompileArgs(args);
+  if ("error" in parsed) {
+    io.stderr.write(`Error: ${parsed.error}
+
+`);
+    printCompileUsage(io.stderr);
+    return 1;
+  }
+  const options = parsed.value;
+  if (!options.profilePath || !options.model) {
+    io.stderr.write("Error: Missing required arguments\n\n");
+    printCompileUsage(io.stderr);
+    return 1;
+  }
+  const profilePath = path.resolve(io.cwd(), options.profilePath);
+  const bundledProfilesDir = options.bundledProfilesDir ? path.resolve(io.cwd(), options.bundledProfilesDir) : path.resolve(io.cwd(), "profiles");
+  const knowledgeBaseDir = options.knowledgeBaseDir ? path.resolve(io.cwd(), options.knowledgeBaseDir) : path.resolve(io.cwd(), "knowledge-base");
+  if (options.verbose) {
+    io.stderr.write(`Compiling: ${profilePath}
+`);
+    io.stderr.write(`Model: ${options.model}
+`);
+    io.stderr.write(`Strict mode: ${options.strict ? "on" : "off"}
+`);
+  }
+  try {
+    const compiled = compileProfile(profilePath, {
+      model: options.model,
+      strict: options.strict,
+      explain: options.explain,
+      context: options.context,
+      bundledProfilesDir,
+      knowledgeBaseDir
+    });
+    const warningCount = compiled.validation?.warnings?.length ?? 0;
+    if (warningCount > 0 && !options.json) {
+      io.stderr.write(`Validation warnings: ${warningCount}
+`);
+    }
+    if (options.json) {
+      io.stdout.write(`${JSON.stringify(compiled, null, 2)}
+`);
+      return 0;
+    }
+    io.stdout.write(`${compiled.text}
+`);
+    if (options.explain && compiled.trace) {
+      io.stdout.write(`
+[TRACE]
+${JSON.stringify(compiled.trace, null, 2)}
+`);
+    }
+    return 0;
+  } catch (error) {
+    const typedError = error;
+    if (typedError.code === "E_COMPILE_VALIDATION" && typedError.validation) {
+      if (options.json) {
+        io.stdout.write(
+          `${JSON.stringify(
+            {
+              error: typedError.message,
+              code: typedError.code,
+              validation: toValidationResultObject(typedError.validation)
+            },
+            null,
+            2
+          )}
+`
+        );
+      } else {
+        io.stderr.write(`${formatValidationResult(typedError.validation)}
+`);
+      }
+      return typedError.validation.exitCode ?? 2;
+    }
+    io.stderr.write(
+      `Error: ${error instanceof Error ? error.message : String(error)}
+`
+    );
+    return 2;
+  }
+}
+function compileHelp(out = process.stdout) {
+  printCompileUsage(out);
+}
+
+// src/commands/eval.ts
+import fs from "fs";
+import path2 from "path";
+import {
+  runTier1EvaluationForProfile,
+  runTier2EvaluationForProfile,
+  runTier3EvaluationForProfile
+} from "@traits-dev/core";
+import {
+  detectEvalTierAvailability,
+  formatValidationResult as formatValidationResult2,
+  resolveTierExecution,
+  runOfflineBaselineScaffold,
+  toValidationResultObject as toValidationResultObject2
+} from "@traits-dev/core/internal";
+function printEvalUsage(out = process.stderr) {
+  out.write(
+    [
+      "Usage:",
+      "  traits eval <profile-path> --model <model> [options]",
+      "",
+      "Options:",
+      "  --model <model>           Model target (required)",
+      "  --tier <1|2|3>            Highest tier to run (default: highest available)",
+      "  --provider <name>         Judge provider for Tier 3: auto|openai|anthropic",
+      "  --embedding-model <name>  Embedding model for Tier 2 (OpenAI)",
+      "  --judge-model <name>      Judge model for Tier 3 provider",
+      "  --openai-base-url <url>   Override OpenAI API base URL",
+      "  --anthropic-base-url <url> Override Anthropic API base URL",
+      "  --timeout-ms <ms>         Provider request timeout (default: 20000)",
+      "  --max-retries <count>     Provider retry attempts (default: 2)",
+      "  --retry-base-ms <ms>      Base backoff delay (default: 250)",
+      "  --response <text>         Assistant response sample (repeatable)",
+      "  --samples <path>          JSON file with samples: [{ id, response }]",
+      "  --scenarios <path>        Alias for --samples in this scaffold",
+      "  --json                    Output structured JSON",
+      "  --strict                  Treat validation warnings as errors",
+      "  --verbose                 Include command metadata output",
+      "  --no-color                Disable colorized output",
+      "  --no-baselines            Skip offline baseline scaffold comparison",
+      "  --no-helpfulness          Skip helpfulness checks in scoring",
+      "  --constraint-impact       Reserved flag (accepted, no-op in scaffold)",
+      ""
+    ].join("\n")
+  );
+}
+function parseEvalArgs(args) {
+  const result = {
+    profilePath: null,
+    model: null,
+    tier: null,
+    provider: "auto",
+    embeddingModel: null,
+    judgeModel: null,
+    openaiBaseUrl: null,
+    anthropicBaseUrl: null,
+    timeoutMs: null,
+    maxRetries: null,
+    retryBaseMs: null,
+    json: false,
+    strict: false,
+    verbose: false,
+    noColor: false,
+    responses: [],
+    samplesPath: null,
+    noBaselines: false,
+    noHelpfulness: false,
+    constraintImpact: false
+  };
+  const positionals = [];
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "--json") {
+      result.json = true;
+      continue;
+    }
+    if (arg === "--strict") {
+      result.strict = true;
+      continue;
+    }
+    if (arg === "--verbose") {
+      result.verbose = true;
+      continue;
+    }
+    if (arg === "--no-color") {
+      result.noColor = true;
+      continue;
+    }
+    if (arg === "--no-baselines") {
+      result.noBaselines = true;
+      continue;
+    }
+    if (arg === "--no-helpfulness") {
+      result.noHelpfulness = true;
+      continue;
+    }
+    if (arg === "--constraint-impact") {
+      result.constraintImpact = true;
+      continue;
+    }
+    if (arg === "--model" || arg === "--tier" || arg === "--provider" || arg === "--embedding-model" || arg === "--judge-model" || arg === "--openai-base-url" || arg === "--anthropic-base-url" || arg === "--timeout-ms" || arg === "--max-retries" || arg === "--retry-base-ms" || arg === "--response" || arg === "--samples" || arg === "--scenarios") {
+      const value = args[index + 1];
+      if (!value) return { error: `Missing value for "${arg}"` };
+      if (arg === "--model") result.model = value;
+      if (arg === "--tier") result.tier = Number(value);
+      if (arg === "--provider") {
+        result.provider = String(value).toLowerCase();
+      }
+      if (arg === "--embedding-model") result.embeddingModel = value;
+      if (arg === "--judge-model") result.judgeModel = value;
+      if (arg === "--openai-base-url") result.openaiBaseUrl = value;
+      if (arg === "--anthropic-base-url") result.anthropicBaseUrl = value;
+      if (arg === "--timeout-ms") result.timeoutMs = Number(value);
+      if (arg === "--max-retries") result.maxRetries = Number(value);
+      if (arg === "--retry-base-ms") result.retryBaseMs = Number(value);
+      if (arg === "--response") result.responses.push(value);
+      if (arg === "--samples" || arg === "--scenarios") result.samplesPath = value;
+      index += 1;
+      continue;
+    }
+    if (arg.startsWith("--")) {
+      return { error: `Unknown option "${arg}"` };
+    }
+    positionals.push(arg);
+  }
+  if (positionals.length !== 1) {
+    return { error: "Expected exactly one profile path argument" };
+  }
+  result.profilePath = positionals[0];
+  if (!result.model) {
+    return { error: 'Missing required option "--model"' };
+  }
+  if (result.tier != null && ![1, 2, 3].includes(result.tier)) {
+    return { error: 'Invalid "--tier" value. Expected 1, 2, or 3.' };
+  }
+  if (!["auto", "openai", "anthropic"].includes(result.provider)) {
+    return { error: 'Invalid "--provider" value. Expected auto, openai, or anthropic.' };
+  }
+  if (result.timeoutMs != null && (!Number.isInteger(result.timeoutMs) || result.timeoutMs < 0)) {
+    return { error: 'Invalid "--timeout-ms" value. Expected a non-negative integer.' };
+  }
+  if (result.maxRetries != null && (!Number.isInteger(result.maxRetries) || result.maxRetries < 0)) {
+    return { error: 'Invalid "--max-retries" value. Expected a non-negative integer.' };
+  }
+  if (result.retryBaseMs != null && (!Number.isInteger(result.retryBaseMs) || result.retryBaseMs < 0)) {
+    return { error: 'Invalid "--retry-base-ms" value. Expected a non-negative integer.' };
+  }
+  return { value: result };
+}
+function loadSamples(options, cwd) {
+  if (options.samplesPath) {
+    const sampleFile = path2.resolve(cwd, options.samplesPath);
+    const parsed = JSON.parse(fs.readFileSync(sampleFile, "utf8"));
+    if (!Array.isArray(parsed)) {
+      throw new Error("Sample file must be a JSON array");
+    }
+    return parsed.map((item, index) => {
+      if (typeof item === "string") {
+        return { id: `sample-${index + 1}`, response: item };
+      }
+      if (!item || typeof item !== "object") {
+        return { id: `sample-${index + 1}`, response: "" };
+      }
+      const sample = item;
+      return {
+        id: sample.id != null ? String(sample.id) : `sample-${index + 1}`,
+        response: String(sample.response ?? ""),
+        prompt: sample.prompt != null ? String(sample.prompt) : void 0
+      };
+    });
+  }
+  return options.responses.map((response, index) => ({
+    id: `sample-${index + 1}`,
+    response
+  }));
+}
+function writeProgress(io, options, message) {
+  if (options.json) return;
+  io.stderr.write(`${message}
+`);
+}
+async function runEval(args, io = process) {
+  const parsed = parseEvalArgs(args);
+  if ("error" in parsed) {
+    io.stderr.write(`Error: ${parsed.error}
+
+`);
+    printEvalUsage(io.stderr);
+    return 1;
+  }
+  const options = parsed.value;
+  if (!options.profilePath || !options.model) {
+    io.stderr.write("Error: Missing required arguments\n\n");
+    printEvalUsage(io.stderr);
+    return 1;
+  }
+  const profilePath = path2.resolve(io.cwd(), options.profilePath);
+  const bundledProfilesDir = path2.resolve(io.cwd(), "profiles");
+  const knowledgeBaseDir = path2.resolve(io.cwd(), "knowledge-base");
+  let samples;
+  try {
+    samples = loadSamples(options, io.cwd());
+  } catch (error) {
+    io.stderr.write(
+      `Error loading samples: ${error instanceof Error ? error.message : String(error)}
+`
+    );
+    return 1;
+  }
+  if (samples.length === 0) {
+    io.stderr.write("Error: Provide at least one --response or a --samples file.\n");
+    return 1;
+  }
+  if (options.verbose) {
+    io.stderr.write(`Eval profile: ${profilePath}
+`);
+    io.stderr.write(`Model: ${options.model}
+`);
+    io.stderr.write(
+      `Requested tier: ${options.tier != null ? options.tier : "auto-highest"}
+`
+    );
+    io.stderr.write(`Provider preference: ${options.provider}
+`);
+    if (options.embeddingModel) {
+      io.stderr.write(`Embedding model: ${options.embeddingModel}
+`);
+    }
+    if (options.judgeModel) {
+      io.stderr.write(`Judge model: ${options.judgeModel}
+`);
+    }
+  }
+  const availability = detectEvalTierAvailability(process.env, {
+    provider: options.provider
+  });
+  const autoRequestedTier = [3, 2, 1].find(
+    (tier) => availability?.[tier]?.available && availability?.[tier]?.implemented
+  ) ?? 1;
+  const requestedTier = options.tier ?? autoRequestedTier;
+  const tierResolution = resolveTierExecution(requestedTier, availability);
+  if (tierResolution.blocked.length > 0 && !options.json) {
+    for (const blocked of tierResolution.blocked) {
+      io.stderr.write(`Tier ${blocked.tier} unavailable: ${blocked.reason}
+`);
+    }
+  }
+  try {
+    const tierReports = {};
+    let baselineReport = null;
+    let evaluation = null;
+    if (tierResolution.tiers_run.includes(1)) {
+      writeProgress(io, options, "Running Tier 1 checks...");
+      evaluation = runTier1EvaluationForProfile(profilePath, samples, {
+        strict: options.strict,
+        bundledProfilesDir,
+        includeHelpfulness: !options.noHelpfulness
+      });
+      tierReports.tier1 = evaluation.report;
+      writeProgress(io, options, "Tier 1 complete.");
+    }
+    if (tierResolution.tiers_run.includes(2)) {
+      writeProgress(io, options, "Running Tier 2 checks...");
+      const tier2 = await runTier2EvaluationForProfile(profilePath, samples, {
+        strict: options.strict,
+        bundledProfilesDir,
+        knowledgeBaseDir,
+        modelTarget: options.model,
+        openaiApiKey: process.env.TRAITS_OPENAI_API_KEY,
+        embeddingModel: options.embeddingModel ?? void 0,
+        openaiBaseUrl: options.openaiBaseUrl ?? void 0,
+        includeHelpfulness: !options.noHelpfulness,
+        fetchTimeoutMs: options.timeoutMs ?? void 0,
+        fetchMaxRetries: options.maxRetries ?? void 0,
+        fetchRetryBaseMs: options.retryBaseMs ?? void 0
+      });
+      tierReports.tier2 = tier2.report;
+      writeProgress(io, options, "Tier 2 complete.");
+    }
+    if (tierResolution.tiers_run.includes(3)) {
+      writeProgress(io, options, "Running Tier 3 checks...");
+      const tier3 = await runTier3EvaluationForProfile(profilePath, samples, {
+        strict: options.strict,
+        bundledProfilesDir,
+        provider: options.provider,
+        judgeModel: options.judgeModel ?? void 0,
+        openaiApiKey: process.env.TRAITS_OPENAI_API_KEY,
+        anthropicApiKey: process.env.TRAITS_ANTHROPIC_API_KEY,
+        openaiBaseUrl: options.openaiBaseUrl ?? void 0,
+        anthropicBaseUrl: options.anthropicBaseUrl ?? void 0,
+        includeHelpfulness: !options.noHelpfulness,
+        fetchTimeoutMs: options.timeoutMs ?? void 0,
+        fetchMaxRetries: options.maxRetries ?? void 0,
+        fetchRetryBaseMs: options.retryBaseMs ?? void 0
+      });
+      tierReports.tier3 = tier3.report;
+      writeProgress(io, options, "Tier 3 complete.");
+    }
+    if (!options.noBaselines && evaluation?.validation?.profile) {
+      writeProgress(io, options, "Running offline baseline scaffold...");
+      baselineReport = runOfflineBaselineScaffold(evaluation.validation.profile, samples, {
+        includeHelpfulness: !options.noHelpfulness,
+        compiledTier1Report: tierReports.tier1
+      });
+      writeProgress(io, options, "Offline baseline scaffold complete.");
+    }
+    const allScores = [
+      tierReports.tier1?.average_score,
+      tierReports.tier2?.average_score,
+      tierReports.tier3?.average_score
+    ].filter((score) => Number.isFinite(score));
+    const overallScore = allScores.length > 0 ? allScores.reduce((sum, value) => sum + value, 0) / allScores.length : 0;
+    const payload = {
+      profile: profilePath,
+      model: options.model,
+      tier_requested: requestedTier,
+      tier_executed: tierResolution.tier_executed,
+      tier_resolution: tierResolution,
+      tier_availability: availability,
+      report: {
+        overall_score: overallScore,
+        ...tierReports,
+        ...baselineReport ? { baselines: baselineReport } : {}
+      }
+    };
+    if (evaluation?.validation) {
+      payload.validation = {
+        warnings: evaluation.validation.warnings.length,
+        errors: evaluation.validation.errors.length
+      };
+    }
+    if (options.json) {
+      io.stdout.write(`${JSON.stringify(payload, null, 2)}
+`);
+      return 0;
+    }
+    if (tierReports.tier1) {
+      io.stdout.write(`Tier 1 average score: ${tierReports.tier1.average_score.toFixed(3)}
+`);
+      for (const sample of tierReports.tier1.samples) {
+        io.stdout.write(`- ${sample.id}: ${sample.score.toFixed(3)}
+`);
+      }
+    }
+    if (tierReports.tier2) {
+      io.stdout.write(`Tier 2 average score: ${tierReports.tier2.average_score.toFixed(3)}
+`);
+    }
+    if (tierReports.tier3) {
+      io.stdout.write(`Tier 3 average score: ${tierReports.tier3.average_score.toFixed(3)}
+`);
+    }
+    if (baselineReport?.tier1) {
+      io.stdout.write(
+        `Baseline (none) Tier 1 avg: ${baselineReport.tier1.none.average_score.toFixed(3)}
+`
+      );
+      io.stdout.write(
+        `Baseline (basic) Tier 1 avg: ${baselineReport.tier1.basic.average_score.toFixed(3)}
+`
+      );
+      const deltas = baselineReport.tier1.deltas ?? {};
+      const compiledVsNone = deltas.compiled_vs_none;
+      if (typeof compiledVsNone === "number" && Number.isFinite(compiledVsNone)) {
+        io.stdout.write(`Delta vs none baseline: ${compiledVsNone.toFixed(3)}
+`);
+      }
+      const compiledVsBasic = deltas.compiled_vs_basic;
+      if (typeof compiledVsBasic === "number" && Number.isFinite(compiledVsBasic)) {
+        io.stdout.write(`Delta vs basic baseline: ${compiledVsBasic.toFixed(3)}
+`);
+      }
+    }
+    io.stdout.write(`Overall eval score: ${overallScore.toFixed(3)}
+`);
+    return 0;
+  } catch (error) {
+    const typedError = error;
+    if ((typedError.code === "E_EVAL_TIER2_UNAVAILABLE" || typedError.code === "E_EVAL_TIER3_UNAVAILABLE") && !options.json) {
+      io.stderr.write(`Error: ${typedError.message ?? "Evaluation tier unavailable."}
+`);
+      return 2;
+    }
+    if ((typedError.code === "E_EVAL_TIER2_UNAVAILABLE" || typedError.code === "E_EVAL_TIER3_UNAVAILABLE") && options.json) {
+      io.stdout.write(
+        `${JSON.stringify(
+          {
+            error: typedError.message,
+            code: typedError.code
+          },
+          null,
+          2
+        )}
+`
+      );
+      return 2;
+    }
+    const validation = typedError.validation;
+    if (typedError.code === "E_EVAL_VALIDATION" && validation) {
+      if (options.json) {
+        io.stdout.write(
+          `${JSON.stringify(
+            {
+              error: typedError.message,
+              code: typedError.code,
+              validation: toValidationResultObject2(validation)
+            },
+            null,
+            2
+          )}
+`
+        );
+      } else {
+        io.stderr.write(`${formatValidationResult2(validation)}
+`);
+      }
+      return validation.exitCode ?? 2;
+    }
+    io.stderr.write(`Error: ${error instanceof Error ? error.message : String(error)}
+`);
+    return 2;
+  }
+}
+function evalHelp(out = process.stdout) {
+  printEvalUsage(out);
+}
+
+// src/commands/init.ts
+import fs2 from "fs";
+import os from "os";
+import path3 from "path";
+import readline from "readline/promises";
+import { validateProfile } from "@traits-dev/core";
+var TONE_PRESETS = {
+  balanced: {
+    formality: { target: "medium", adapt: true, floor: "low", ceiling: "high" },
+    warmth: { target: "medium", adapt: true, floor: "low", ceiling: "high" },
+    verbosity: { target: "medium", adapt: true, floor: "low", ceiling: "high" },
+    directness: "medium",
+    empathy: { target: "medium", adapt: true, floor: "low", ceiling: "high" },
+    humor: { target: "very-low", style: "none" }
+  },
+  warm: {
+    formality: { target: "medium", adapt: true, floor: "low", ceiling: "high" },
+    warmth: { target: "high", adapt: true, floor: "medium", ceiling: "very-high" },
+    verbosity: { target: "medium", adapt: true, floor: "low", ceiling: "high" },
+    directness: "medium",
+    empathy: { target: "high", adapt: true, floor: "medium", ceiling: "very-high" },
+    humor: { target: "very-low", style: "none" }
+  },
+  direct: {
+    formality: { target: "medium", adapt: true, floor: "low", ceiling: "high" },
+    warmth: { target: "medium", adapt: true, floor: "low", ceiling: "high" },
+    verbosity: { target: "low", adapt: true, floor: "low", ceiling: "medium" },
+    directness: "high",
+    empathy: { target: "medium", adapt: true, floor: "low", ceiling: "high" },
+    humor: { target: "very-low", style: "none" }
+  },
+  formal: {
+    formality: { target: "high", adapt: true, floor: "medium", ceiling: "very-high" },
+    warmth: { target: "medium", adapt: true, floor: "low", ceiling: "high" },
+    verbosity: { target: "medium", adapt: true, floor: "low", ceiling: "high" },
+    directness: "medium",
+    empathy: { target: "medium", adapt: true, floor: "low", ceiling: "high" },
+    humor: { target: "very-low", style: "none" }
+  }
+};
+function printInitUsage(out = process.stderr) {
+  out.write(
+    [
+      "Usage:",
+      "  traits init [output-path] [options]",
+      "",
+      "Options:",
+      "  --name <name>             Profile name",
+      "  --domain <domain>         Domain or vertical",
+      "  --model <model>           Primary model target metadata (tag only)",
+      "  --tone <tone>             Tone preset: balanced|warm|direct|formal",
+      "  --template <profile>      Start from a starter profile (e.g., resolve)",
+      "  --verbose                 Include additional command metadata",
+      "  --no-color                Disable colorized output",
+      "  --force                   Overwrite output file if it exists",
+      ""
+    ].join("\n")
+  );
+}
+function slugify(value) {
+  return String(value).trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+}
+function toTitleWords(value) {
+  return String(value).split(/[-_\s]+/g).filter(Boolean).map((part) => `${part.slice(0, 1).toUpperCase()}${part.slice(1)}`).join(" ");
+}
+function renderDimensionBlock(key, value) {
+  if (typeof value === "string") {
+    return [`  ${key}: "${value}"`];
+  }
+  const lines = [`  ${key}:`];
+  lines.push(`    target: "${value.target}"`);
+  if (value.adapt != null) lines.push(`    adapt: ${value.adapt ? "true" : "false"}`);
+  if (value.floor != null) lines.push(`    floor: "${value.floor}"`);
+  if (value.ceiling != null) lines.push(`    ceiling: "${value.ceiling}"`);
+  if (value.style != null) lines.push(`    style: "${value.style}"`);
+  return lines;
+}
+function renderScaffold({
+  name,
+  domain,
+  model,
+  tone
+}) {
+  const domainLabel = String(domain).trim();
+  const preset = TONE_PRESETS[tone] ?? TONE_PRESETS.balanced;
+  const role = `${toTitleWords(domainLabel)} assistant`;
+  const expertise = `${toTitleWords(domainLabel)} workflows and support`;
+  return [
+    "# traits.dev personality scaffold",
+    "# Edit fields to match your product and voice requirements.",
+    'schema: "v1.4"',
+    "",
+    "meta:",
+    `  name: "${name}"`,
+    '  version: "1.0.0"',
+    `  description: "${toTitleWords(domainLabel)} assistant profile scaffold"`,
+    "  tags:",
+    `    - "${slugify(domainLabel) || "general"}"`,
+    `    - "model:${model}"`,
+    '  target_audience: "Users who need reliable help"',
+    "",
+    "identity:",
+    `  role: "${role}"`,
+    "  backstory: >",
+    "    You are a practical, trustworthy assistant that helps users",
+    "    complete tasks with clear next steps and explicit boundaries.",
+    "  expertise_domains:",
+    `    - "${expertise}"`,
+    "",
+    "voice:",
+    "  # Levels: very-low | low | medium | high | very-high",
+    ...renderDimensionBlock("formality", preset.formality),
+    ...renderDimensionBlock("warmth", preset.warmth),
+    ...renderDimensionBlock("verbosity", preset.verbosity),
+    ...renderDimensionBlock("directness", preset.directness),
+    ...renderDimensionBlock("empathy", preset.empathy),
+    ...renderDimensionBlock("humor", preset.humor),
+    "",
+    "vocabulary:",
+    "  preferred_terms:",
+    `    - "Here's what I can do"`,
+    "  forbidden_terms:",
+    '    - "always"',
+    "",
+    "behavioral_rules:",
+    '  - "Answer with concrete steps before optional background details"',
+    '  - "State uncertainty explicitly when information is incomplete"',
+    "",
+    "context_adaptations:",
+    '  - when: "frustrated_user"',
+    "    adjustments:",
+    "      warmth:",
+    '        target: "high"',
+    "        adapt: false",
+    "    inject:",
+    '      - "Acknowledge frustration first, then provide one clear next step"',
+    "",
+    "# Reserved sections for future use:",
+    "# localization: {}",
+    "# channel_adaptations: {}",
+    ""
+  ].join("\n");
+}
+function parseInitArgs(args) {
+  const result = {
+    outputPath: null,
+    name: null,
+    domain: null,
+    model: null,
+    tone: null,
+    template: null,
+    verbose: false,
+    noColor: false,
+    force: false
+  };
+  const positionals = [];
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "--force") {
+      result.force = true;
+      continue;
+    }
+    if (arg === "--verbose") {
+      result.verbose = true;
+      continue;
+    }
+    if (arg === "--no-color") {
+      result.noColor = true;
+      continue;
+    }
+    if (arg === "--name" || arg === "--domain" || arg === "--model" || arg === "--tone" || arg === "--template") {
+      const value = args[index + 1];
+      if (!value) return { error: `Missing value for "${arg}"` };
+      if (arg === "--name") result.name = value;
+      if (arg === "--domain") result.domain = value;
+      if (arg === "--model") result.model = value;
+      if (arg === "--tone") result.tone = value;
+      if (arg === "--template") result.template = value;
+      index += 1;
+      continue;
+    }
+    if (arg.startsWith("--")) {
+      return { error: `Unknown option "${arg}"` };
+    }
+    positionals.push(arg);
+  }
+  if (positionals.length > 1) {
+    return { error: "Expected at most one output path argument" };
+  }
+  result.outputPath = positionals[0] ?? null;
+  if (result.tone && !Object.hasOwn(TONE_PRESETS, result.tone)) {
+    return {
+      error: `Invalid tone "${result.tone}". Expected one of: ${Object.keys(TONE_PRESETS).join(", ")}`
+    };
+  }
+  return { value: result };
+}
+function resolveTemplatePath(template, cwd) {
+  const candidateValues = [template];
+  if (!template.endsWith(".yaml")) {
+    candidateValues.push(`${template}.yaml`);
+  }
+  for (const candidate of candidateValues) {
+    const absoluteCandidate = path3.isAbsolute(candidate) ? candidate : path3.resolve(cwd, candidate);
+    if (fs2.existsSync(absoluteCandidate)) return absoluteCandidate;
+    const starterCandidate = path3.resolve(cwd, "profiles", candidate);
+    if (fs2.existsSync(starterCandidate)) return starterCandidate;
+  }
+  return null;
+}
+async function promptIfMissing(config, io) {
+  const out = { ...config };
+  const stdout = io.stdout;
+  if (!io.stdin.isTTY || !stdout.isTTY) {
+    out.name = out.name ?? "my-profile";
+    out.domain = out.domain ?? "general-assistant";
+    out.model = out.model ?? "claude-sonnet";
+    out.tone = out.tone ?? "balanced";
+    return out;
+  }
+  const rl = readline.createInterface({ input: io.stdin, output: stdout });
+  try {
+    const nameInput = out.name ?? await rl.question("Profile name (my-profile): ");
+    out.name = nameInput.trim() || "my-profile";
+    const domainInput = out.domain ?? await rl.question("Domain or vertical (general-assistant): ");
+    out.domain = domainInput.trim() || "general-assistant";
+    const modelInput = out.model ?? await rl.question("Model target tag (claude-sonnet): ");
+    out.model = modelInput.trim() || "claude-sonnet";
+    const toneInput = out.tone ?? await rl.question("Tone preset [balanced|warm|direct|formal] (balanced): ");
+    out.tone = toneInput.trim() || "balanced";
+    if (!Object.hasOwn(TONE_PRESETS, out.tone)) {
+      out.tone = "balanced";
+    }
+  } finally {
+    rl.close();
+  }
+  return out;
+}
+function resolveOutputPath(cwd, options) {
+  if (options.outputPath) return path3.resolve(cwd, options.outputPath);
+  if (options.template) {
+    const base = slugify(path3.basename(options.template, path3.extname(options.template)));
+    return path3.resolve(cwd, `${base || "profile"}-custom.yaml`);
+  }
+  return path3.resolve(cwd, `${slugify(options.name ?? "") || "profile"}.yaml`);
+}
+function ensureWritableTarget(filePath, force) {
+  if (!fs2.existsSync(filePath)) return { ok: true };
+  if (force) return { ok: true };
+  return {
+    ok: false,
+    message: `File already exists: ${filePath}. Use --force to overwrite.`
+  };
+}
+function writeFileAtomic(filePath, contents) {
+  fs2.mkdirSync(path3.dirname(filePath), { recursive: true });
+  const tempFile = path3.join(
+    path3.dirname(filePath),
+    `.${path3.basename(filePath)}.${Date.now()}.${Math.random().toString(16).slice(2)}.tmp`
+  );
+  fs2.writeFileSync(tempFile, contents, "utf8");
+  fs2.renameSync(tempFile, filePath);
+}
+async function runInit(args, io = process) {
+  const parsed = parseInitArgs(args);
+  if ("error" in parsed) {
+    io.stderr.write(`Error: ${parsed.error}
+
+`);
+    printInitUsage(io.stderr);
+    return 1;
+  }
+  let options = parsed.value;
+  const cwd = io.cwd();
+  if (options.template) {
+    const templatePath = resolveTemplatePath(options.template, cwd);
+    if (!templatePath) {
+      io.stderr.write(`Error: Unable to resolve template "${options.template}"
+`);
+      return 1;
+    }
+    const outputPath2 = resolveOutputPath(cwd, options);
+    const writableCheck2 = ensureWritableTarget(outputPath2, options.force);
+    if (!writableCheck2.ok) {
+      io.stderr.write(`Error: ${writableCheck2.message}
+`);
+      return 1;
+    }
+    const templateContent = fs2.readFileSync(templatePath, "utf8");
+    writeFileAtomic(outputPath2, templateContent);
+    if (options.verbose) {
+      io.stdout.write(`Template source: ${templatePath}
+`);
+    }
+    io.stdout.write(`Created profile from template at ${outputPath2}
+`);
+    return 0;
+  }
+  options = await promptIfMissing(options, io);
+  const outputPath = resolveOutputPath(cwd, options);
+  const writableCheck = ensureWritableTarget(outputPath, options.force);
+  if (!writableCheck.ok) {
+    io.stderr.write(`Error: ${writableCheck.message}
+`);
+    return 1;
+  }
+  const content = renderScaffold({
+    name: options.name ?? "my-profile",
+    domain: options.domain ?? "general-assistant",
+    model: options.model ?? "claude-sonnet",
+    tone: options.tone ?? "balanced"
+  });
+  writeFileAtomic(outputPath, content);
+  if (options.verbose) {
+    io.stdout.write(
+      `Scaffold config: name=${options.name ?? "my-profile"}, domain=${options.domain ?? "general-assistant"}, model=${options.model ?? "claude-sonnet"}, tone=${options.tone ?? "balanced"}
+`
+    );
+  }
+  const validation = validateProfile(outputPath, {
+    bundledProfilesDir: path3.resolve(cwd, "profiles")
+  });
+  if (validation.errors.length > 0) {
+    io.stderr.write(
+      `Error: Generated profile failed validation (${validation.errors.length} errors).
+`
+    );
+    return 2;
+  }
+  io.stdout.write(`Created profile scaffold at ${outputPath}
+`);
+  if (validation.warnings.length > 0) {
+    io.stdout.write(`Validation warnings: ${validation.warnings.length}
+`);
+  }
+  return 0;
+}
+function initHelp(out = process.stdout) {
+  printInitUsage(out);
+}
+
+// src/commands/import.ts
+import fs3 from "fs";
+import path4 from "path";
+import { runImportAnalysis, validateResolvedProfile } from "@traits-dev/core";
+import {
+  formatValidationResult as formatValidationResult3,
+  toValidationResultObject as toValidationResultObject3
+} from "@traits-dev/core/internal";
+function printImportUsage(out = process.stderr) {
+  out.write(
+    [
+      "Usage:",
+      "  traits import [prompt-path] [options]",
+      "",
+      "Options:",
+      "  --provider <name>         Import provider: auto|openai|anthropic (default: auto)",
+      "  --model <model>           Import analysis model override",
+      "  --name <profile-name>     Output profile meta.name override",
+      "  --output <path>           Write generated YAML profile to file",
+      "  --openai-base-url <url>   Override OpenAI API base URL",
+      "  --anthropic-base-url <url> Override Anthropic API base URL",
+      "  --timeout-ms <ms>         Provider request timeout (default: 20000)",
+      "  --max-retries <count>     Provider retry attempts (default: 2)",
+      "  --retry-base-ms <ms>      Base backoff delay (default: 250)",
+      "  --strict                  Treat validation warnings as errors",
+      "  --json                    Output structured JSON",
+      "  --verbose                 Include command metadata output",
+      "  --no-color                Disable colorized output",
+      "",
+      "Input:",
+      "  prompt-path               Existing system prompt text file",
+      "  (stdin)                   Pipe prompt text when prompt-path is omitted",
+      ""
+    ].join("\n")
+  );
+}
+function parseImportArgs(args) {
+  const result = {
+    promptPath: null,
+    provider: "auto",
+    model: null,
+    profileName: null,
+    outputPath: null,
+    openaiBaseUrl: null,
+    anthropicBaseUrl: null,
+    timeoutMs: null,
+    maxRetries: null,
+    retryBaseMs: null,
+    strict: false,
+    json: false,
+    verbose: false,
+    noColor: false
+  };
+  const positionals = [];
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "--strict") {
+      result.strict = true;
+      continue;
+    }
+    if (arg === "--json") {
+      result.json = true;
+      continue;
+    }
+    if (arg === "--verbose") {
+      result.verbose = true;
+      continue;
+    }
+    if (arg === "--no-color") {
+      result.noColor = true;
+      continue;
+    }
+    if (arg === "--provider" || arg === "--model" || arg === "--name" || arg === "--output" || arg === "--openai-base-url" || arg === "--anthropic-base-url" || arg === "--timeout-ms" || arg === "--max-retries" || arg === "--retry-base-ms") {
+      const value = args[index + 1];
+      if (!value) return { error: `Missing value for "${arg}"` };
+      if (arg === "--provider") result.provider = String(value).toLowerCase();
+      if (arg === "--model") result.model = value;
+      if (arg === "--name") result.profileName = value;
+      if (arg === "--output") result.outputPath = value;
+      if (arg === "--openai-base-url") result.openaiBaseUrl = value;
+      if (arg === "--anthropic-base-url") result.anthropicBaseUrl = value;
+      if (arg === "--timeout-ms") result.timeoutMs = Number(value);
+      if (arg === "--max-retries") result.maxRetries = Number(value);
+      if (arg === "--retry-base-ms") result.retryBaseMs = Number(value);
+      index += 1;
+      continue;
+    }
+    if (arg.startsWith("--")) {
+      return { error: `Unknown option "${arg}"` };
+    }
+    positionals.push(arg);
+  }
+  if (positionals.length > 1) {
+    return { error: "Expected zero or one prompt path argument" };
+  }
+  result.promptPath = positionals[0] ?? null;
+  if (!["auto", "openai", "anthropic"].includes(result.provider)) {
+    return { error: 'Invalid "--provider" value. Expected auto, openai, or anthropic.' };
+  }
+  if (result.timeoutMs != null && (!Number.isInteger(result.timeoutMs) || result.timeoutMs < 0)) {
+    return { error: 'Invalid "--timeout-ms" value. Expected a non-negative integer.' };
+  }
+  if (result.maxRetries != null && (!Number.isInteger(result.maxRetries) || result.maxRetries < 0)) {
+    return { error: 'Invalid "--max-retries" value. Expected a non-negative integer.' };
+  }
+  if (result.retryBaseMs != null && (!Number.isInteger(result.retryBaseMs) || result.retryBaseMs < 0)) {
+    return { error: 'Invalid "--retry-base-ms" value. Expected a non-negative integer.' };
+  }
+  return { value: result };
+}
+async function readStream(stream) {
+  const chunks = [];
+  for await (const chunk of stream) {
+    chunks.push(typeof chunk === "string" ? chunk : Buffer.from(chunk).toString("utf8"));
+  }
+  return chunks.join("");
+}
+async function loadPromptSource(options, io) {
+  if (options.promptPath) {
+    const promptPath = path4.resolve(io.cwd(), options.promptPath);
+    return {
+      source: promptPath,
+      text: fs3.readFileSync(promptPath, "utf8")
+    };
+  }
+  const stdin = io.stdin ?? process.stdin;
+  if (stdin.isTTY) {
+    throw new Error("Provide a prompt file path or pipe prompt text via stdin.");
+  }
+  return {
+    source: "stdin",
+    text: await readStream(stdin)
+  };
+}
+async function runImport(args, io = process) {
+  const parsed = parseImportArgs(args);
+  if ("error" in parsed) {
+    io.stderr.write(`Error: ${parsed.error}
+
+`);
+    printImportUsage(io.stderr);
+    return 1;
+  }
+  const options = parsed.value;
+  let promptSource;
+  try {
+    promptSource = await loadPromptSource(options, io);
+  } catch (error) {
+    io.stderr.write(`Error: ${error instanceof Error ? error.message : String(error)}
+`);
+    return 1;
+  }
+  const promptText = String(promptSource.text ?? "").trim();
+  if (!promptText) {
+    io.stderr.write("Error: Prompt source is empty.\n");
+    return 1;
+  }
+  if (options.verbose) {
+    io.stderr.write(`Import source: ${promptSource.source}
+`);
+    io.stderr.write(`Provider preference: ${options.provider}
+`);
+    if (options.model) {
+      io.stderr.write(`Model override: ${options.model}
+`);
+    }
+  }
+  try {
+    const imported = await runImportAnalysis(promptText, {
+      provider: options.provider,
+      model: options.model ?? void 0,
+      profileName: options.profileName ?? void 0,
+      openaiApiKey: process.env.TRAITS_OPENAI_API_KEY,
+      anthropicApiKey: process.env.TRAITS_ANTHROPIC_API_KEY,
+      openaiBaseUrl: options.openaiBaseUrl ?? void 0,
+      anthropicBaseUrl: options.anthropicBaseUrl ?? void 0,
+      fetchTimeoutMs: options.timeoutMs ?? void 0,
+      fetchMaxRetries: options.maxRetries ?? void 0,
+      fetchRetryBaseMs: options.retryBaseMs ?? void 0
+    });
+    const validation = validateResolvedProfile(imported.profile, {
+      strict: options.strict
+    });
+    const outputPath = options.outputPath ? path4.resolve(io.cwd(), options.outputPath) : null;
+    if (outputPath) {
+      fs3.writeFileSync(outputPath, imported.yaml, "utf8");
+    }
+    if (options.json) {
+      io.stdout.write(
+        `${JSON.stringify(
+          {
+            provider: imported.provider,
+            source: promptSource.source,
+            output_path: outputPath,
+            profile: imported.profile,
+            analysis: imported.analysis,
+            validation: toValidationResultObject3(validation),
+            yaml: outputPath ? void 0 : imported.yaml
+          },
+          null,
+          2
+        )}
+`
+      );
+      return validation.exitCode ?? 0;
+    }
+    if (!outputPath) {
+      io.stdout.write(`${imported.yaml.trimEnd()}
+`);
+    } else {
+      io.stdout.write(`Wrote imported profile to ${outputPath}
+`);
+    }
+    io.stderr.write(`
+[Validation]
+${formatValidationResult3(validation)}
+`);
+    io.stderr.write("\nNext: run `traits eval <profile-path> --model <model>` to verify fit.\n");
+    return validation.exitCode ?? 0;
+  } catch (error) {
+    const typedError = error;
+    if (typedError.code === "E_IMPORT_PROVIDER_UNAVAILABLE") {
+      if (options.json) {
+        io.stdout.write(
+          `${JSON.stringify(
+            {
+              error: typedError.message,
+              code: typedError.code
+            },
+            null,
+            2
+          )}
+`
+        );
+      } else {
+        io.stderr.write(`Error: ${typedError.message ?? "Import provider unavailable."}
+`);
+      }
+      return 2;
+    }
+    io.stderr.write(`Error: ${error instanceof Error ? error.message : String(error)}
+`);
+    return 2;
+  }
+}
+function importHelp(out = process.stdout) {
+  printImportUsage(out);
+}
+
+// src/commands/validate.ts
+import path5 from "path";
+import { validateProfile as validateProfile2 } from "@traits-dev/core";
+import {
+  formatValidationResult as formatValidationResult4,
+  toValidationResultObject as toValidationResultObject4
+} from "@traits-dev/core/internal";
+function printValidateUsage(out = process.stderr) {
+  out.write(
+    [
+      "Usage:",
+      "  traits validate <profile-path> [--json] [--strict] [--bundled-profiles-dir <dir>]",
+      "",
+      "Options:",
+      "  --json                   Output structured JSON",
+      "  --strict                 Promote warnings to errors",
+      "  --verbose                Include additional command metadata",
+      "  --no-color               Disable colorized output",
+      "  --bundled-profiles-dir   Directory for bundled starter profiles",
+      ""
+    ].join("\n")
+  );
+}
+function parseValidateArgs(args) {
+  const result = {
+    profilePath: null,
+    strict: false,
+    json: false,
+    verbose: false,
+    noColor: false,
+    bundledProfilesDir: null
+  };
+  const positionals = [];
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "--strict") {
+      result.strict = true;
+      continue;
+    }
+    if (arg === "--json") {
+      result.json = true;
+      continue;
+    }
+    if (arg === "--verbose") {
+      result.verbose = true;
+      continue;
+    }
+    if (arg === "--no-color") {
+      result.noColor = true;
+      continue;
+    }
+    if (arg === "--bundled-profiles-dir") {
+      const nextValue = args[index + 1];
+      if (!nextValue) {
+        return { error: 'Missing value for "--bundled-profiles-dir"' };
+      }
+      result.bundledProfilesDir = nextValue;
+      index += 1;
+      continue;
+    }
+    if (arg.startsWith("--")) {
+      return { error: `Unknown option "${arg}"` };
+    }
+    positionals.push(arg);
+  }
+  if (positionals.length !== 1) {
+    return { error: "Expected exactly one profile path argument" };
+  }
+  result.profilePath = positionals[0];
+  return { value: result };
+}
+function runValidate(args, io = process) {
+  const parsed = parseValidateArgs(args);
+  if ("error" in parsed) {
+    io.stderr.write(`Error: ${parsed.error}
+
+`);
+    printValidateUsage(io.stderr);
+    return 1;
+  }
+  const options = parsed.value;
+  if (!options.profilePath) {
+    io.stderr.write("Error: Missing profile path\n\n");
+    printValidateUsage(io.stderr);
+    return 1;
+  }
+  const bundledProfilesDir = options.bundledProfilesDir ? path5.resolve(io.cwd(), options.bundledProfilesDir) : path5.resolve(io.cwd(), "profiles");
+  const profilePath = path5.resolve(io.cwd(), options.profilePath);
+  const result = validateProfile2(profilePath, {
+    strict: options.strict,
+    bundledProfilesDir
+  });
+  if (options.json) {
+    io.stdout.write(`${JSON.stringify(toValidationResultObject4(result), null, 2)}
+`);
+  } else {
+    if (options.verbose) {
+      io.stdout.write(`Profile path: ${profilePath}
+`);
+      io.stdout.write(`Bundled profiles dir: ${bundledProfilesDir}
+`);
+      io.stdout.write(`Strict mode: ${options.strict ? "on" : "off"}
+
+`);
+    }
+    io.stdout.write(`${formatValidationResult4(result)}
+`);
+  }
+  return result.exitCode;
+}
+function validateHelp(out = process.stdout) {
+  printValidateUsage(out);
+}
+
+// src/bin/traits.ts
+var CLI_DIR = path6.dirname(fileURLToPath(import.meta.url));
+var PACKAGE_JSON_CANDIDATES = [
+  path6.resolve(CLI_DIR, "../package.json"),
+  path6.resolve(CLI_DIR, "../../package.json")
+];
+function resolvePackageJsonPath() {
+  for (const candidate of PACKAGE_JSON_CANDIDATES) {
+    if (fs4.existsSync(candidate)) return candidate;
+  }
+  return PACKAGE_JSON_CANDIDATES[0];
+}
+var PACKAGE_JSON_PATH = resolvePackageJsonPath();
+function printRootUsage(out = process.stdout) {
+  out.write(
+    [
+      "traits.dev CLI",
+      "",
+      "Usage:",
+      "  traits [global-options] <command> [options]",
+      "",
+      "Commands:",
+      "  init [output-path]        Create a profile scaffold",
+      "  compile <profile-path>    Compile a profile for a target model",
+      "  eval <profile-path>       Evaluate profile responses (Tier 1 scaffold)",
+      "  import [prompt-path]      Import a profile from an existing system prompt",
+      "  validate <profile-path>   Validate a personality profile",
+      "",
+      "Global flags:",
+      "  --json                    Output JSON where supported",
+      "  --verbose                 Print command metadata",
+      "  --no-color                Disable colorized output",
+      "  --version                 Show CLI version",
+      "  --help, -h                Show help",
+      "",
+      "Examples:",
+      "  traits init my-profile.yaml --domain customer-support --tone warm",
+      "  traits validate profiles/resolve.yaml",
+      "  traits --json validate profiles/haven.yaml --strict",
+      ""
+    ].join("\n")
+  );
+}
+function readCliVersion() {
+  try {
+    const raw = fs4.readFileSync(PACKAGE_JSON_PATH, "utf8");
+    const pkg = JSON.parse(raw);
+    return String(pkg.version ?? "0.0.0");
+  } catch {
+    return "0.0.0";
+  }
+}
+function parseGlobalFlags(args) {
+  const flags = { json: false, verbose: false, noColor: false };
+  let index = 0;
+  while (index < args.length) {
+    const arg = args[index];
+    if (arg === "--json") {
+      flags.json = true;
+      index += 1;
+      continue;
+    }
+    if (arg === "--verbose") {
+      flags.verbose = true;
+      index += 1;
+      continue;
+    }
+    if (arg === "--no-color") {
+      flags.noColor = true;
+      index += 1;
+      continue;
+    }
+    if (arg.startsWith("-")) {
+      return { error: `Unknown global option "${arg}"` };
+    }
+    break;
+  }
+  return {
+    flags,
+    command: args[index] ?? null,
+    commandArgs: args.slice(index + 1)
+  };
+}
+function withGlobalFlags(command, commandArgs, flags) {
+  const args = [...commandArgs];
+  if (flags.verbose && !args.includes("--verbose")) {
+    args.push("--verbose");
+  }
+  if (flags.noColor && !args.includes("--no-color")) {
+    args.push("--no-color");
+  }
+  if ((command === "validate" || command === "compile" || command === "eval" || command === "import") && flags.json && !args.includes("--json")) {
+    args.push("--json");
+  }
+  return args;
+}
+async function run(argv, io = process) {
+  const args = [...argv];
+  if (args.length === 0 || args[0] === "--help" || args[0] === "-h") {
+    printRootUsage(io.stdout);
+    return 0;
+  }
+  if (args[0] === "--version") {
+    io.stdout.write(`${readCliVersion()}
+`);
+    return 0;
+  }
+  const parsed = parseGlobalFlags(args);
+  if ("error" in parsed) {
+    io.stderr.write(`Error: ${parsed.error}
+
+`);
+    printRootUsage(io.stderr);
+    return 1;
+  }
+  const command = parsed.command;
+  if (!command) {
+    io.stderr.write("Error: Missing command\n\n");
+    printRootUsage(io.stderr);
+    return 1;
+  }
+  const commandArgs = withGlobalFlags(command, parsed.commandArgs, parsed.flags);
+  if (command === "validate") {
+    if (commandArgs.includes("--help") || commandArgs.includes("-h")) {
+      validateHelp(io.stdout);
+      return 0;
+    }
+    return runValidate(commandArgs, io);
+  }
+  if (command === "init") {
+    if (commandArgs.includes("--help") || commandArgs.includes("-h")) {
+      initHelp(io.stdout);
+      return 0;
+    }
+    return runInit(commandArgs, io);
+  }
+  if (command === "compile") {
+    if (commandArgs.includes("--help") || commandArgs.includes("-h")) {
+      compileHelp(io.stdout);
+      return 0;
+    }
+    return runCompile(commandArgs, io);
+  }
+  if (command === "eval") {
+    if (commandArgs.includes("--help") || commandArgs.includes("-h")) {
+      evalHelp(io.stdout);
+      return 0;
+    }
+    return runEval(commandArgs, io);
+  }
+  if (command === "import") {
+    if (commandArgs.includes("--help") || commandArgs.includes("-h")) {
+      importHelp(io.stdout);
+      return 0;
+    }
+    return runImport(commandArgs, io);
+  }
+  io.stderr.write(`Error: Unknown command "${command}"
+
+`);
+  printRootUsage(io.stderr);
+  return 1;
+}
+var code = await run(process.argv.slice(2), process);
+process.exitCode = code;
+export {
+  run
+};