orizu 0.5.19 → 0.5.21

package/src/gepa-engine-dispatch.ts

@@ -0,0 +1,340 @@
+import { existsSync, readFileSync } from 'fs'
+
+export type GepaEngine = 'official' | 'legacy'
+
+export interface GepaEngineDispatch {
+  engine: GepaEngine
+  args: string[]
+  environment: NodeJS.ProcessEnv
+  module: string
+}
+
+interface EnvironmentOption {
+  flag: string
+  environment: string
+  readFile?: boolean
+  json?: boolean
+  allowEmpty?: boolean
+}
+
+const VALUE_OPTIONS: EnvironmentOption[] = [
+  { flag: '--optimizer-version-id', environment: 'ORIZU_OPTIMIZER_VERSION_ID' },
+  { flag: '--candidate-version-id', environment: 'ORIZU_PROMPT_VERSION_ID' },
+  { flag: '--runner-version-id', environment: 'ORIZU_RUNNER_VERSION_ID' },
+  { flag: '--candidate-runner-dir', environment: 'ORIZU_CANDIDATE_RUNNER_DIR' },
+  { flag: '--scorer-version-id', environment: 'ORIZU_SCORER_VERSION_ID' },
+  { flag: '--scorer-runner-version-id', environment: 'ORIZU_SCORER_RUNNER_VERSION_ID' },
+  { flag: '--scorer-runner-dir', environment: 'ORIZU_SCORER_RUNNER_DIR' },
+  { flag: '--scorer-input-contract', environment: 'ORIZU_SCORER_INPUT_CONTRACT' },
+  { flag: '--scorer-candidate-field', environment: 'ORIZU_SCORER_CANDIDATE_FIELD' },
+  { flag: '--dataset-version-id', environment: 'ORIZU_DATASET_VERSION_ID' },
+  { flag: '--split-set-id', environment: 'ORIZU_SPLIT_SET_ID' },
+  { flag: '--train-split', environment: 'ORIZU_TRAIN_SPLIT', allowEmpty: true },
+  { flag: '--val-split', environment: 'ORIZU_VALIDATION_SPLIT', allowEmpty: true },
+  { flag: '--budget', environment: 'ORIZU_BUDGET' },
+  { flag: '--max-iterations', environment: 'ORIZU_MAX_ITERATIONS' },
+  { flag: '--max-candidate-proposals', environment: 'ORIZU_MAX_CANDIDATE_PROPOSALS' },
+  { flag: '--proposal-max-calls', environment: 'ORIZU_PROPOSAL_MAX_CALLS' },
+  { flag: '--proposal-max-tokens', environment: 'ORIZU_PROPOSAL_MAX_TOKENS' },
+  { flag: '--max-full-evals', environment: 'ORIZU_MAX_FULL_EVALS' },
+  { flag: '--max-metric-calls', environment: 'ORIZU_MAX_METRIC_CALLS' },
+  { flag: '--minibatch-size', environment: 'ORIZU_MINIBATCH_SIZE' },
+  { flag: '--num-threads', environment: 'ORIZU_NUM_THREADS' },
+  { flag: '--candidate-selection-strategy', environment: 'ORIZU_CANDIDATE_SELECTION_STRATEGY' },
+  { flag: '--epsilon', environment: 'ORIZU_EPSILON' },
+  { flag: '--reflection-model', environment: 'ORIZU_REFLECTION_MODEL' },
+  { flag: '--reflection-temperature', environment: 'ORIZU_REFLECTION_TEMPERATURE' },
+  { flag: '--reflection-max-tokens', environment: 'ORIZU_REFLECTION_MAX_TOKENS' },
+  { flag: '--reflection-retry-attempts', environment: 'ORIZU_REFLECTION_RETRY_ATTEMPTS' },
+  { flag: '--reflection-http-timeout-seconds', environment: 'ORIZU_REFLECTION_HTTP_TIMEOUT_SECONDS' },
+  { flag: '--reflection-prompt-template', environment: 'ORIZU_REFLECTION_PROMPT_TEMPLATE', readFile: true },
+  { flag: '--reflection-provider-settings', environment: 'ORIZU_REFLECTION_PROVIDER_SETTINGS', readFile: true, json: true },
+  { flag: '--objective', environment: 'ORIZU_OBJECTIVE', allowEmpty: true },
+  { flag: '--seed', environment: 'ORIZU_SEED' },
+  { flag: '--promotion-label', environment: 'ORIZU_PROMOTION_LABEL', allowEmpty: true },
+  { flag: '--log-dir', environment: 'ORIZU_LOCAL_LOG_DIR' },
+  { flag: '--instruction-set', environment: 'ORIZU_INSTRUCTION_SET_NAME' },
+  { flag: '--model-config', environment: 'ORIZU_MODEL_CONFIG_IDENTITY' },
+]
+
+const BOOLEAN_OPTIONS = [
+  ['--allow-degenerate-seed', 'ORIZU_ALLOW_DEGENERATE_SEED', '1'],
+  ['--disable-evaluation-cache', 'ORIZU_DISABLE_EVALUATION_CACHE', '1'],
+  ['--auto-promote', 'ORIZU_AUTO_PROMOTE', '1'],
+  ['--log-row-snapshots', 'ORIZU_LOG_ROW_SNAPSHOTS', '1'],
+  ['--no-local-log', 'ORIZU_NO_LOCAL_LOG', '1'],
+  ['--skip-perfect-parent-reflection', 'ORIZU_SKIP_PERFECT_PARENT_REFLECTION', '1'],
+  ['--no-skip-perfect-parent-reflection', 'ORIZU_SKIP_PERFECT_PARENT_REFLECTION', '0'],
+] as const
+
+function textValue(value: string): string {
+  if (value.startsWith('@')) return readFileSync(value.slice(1), 'utf8')
+  const path = value
+  return existsSync(path) ? readFileSync(path, 'utf8') : value
+}
+
+function jsonObjectValue(value: string, flag: string): string {
+  const raw = textValue(value)
+  const parsed: unknown = JSON.parse(raw)
+  if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+    throw new Error(`${flag} must be a JSON object`)
+  }
+  // Validate in JavaScript, but preserve the raw spelling for Python's JSON
+  // parser so large numbers and exponent forms do not lose precision here.
+  return raw
+}
+
+function removeEngine(args: string[]): { engine: GepaEngine; args: string[] } {
+  let engine: string | undefined
+  const forwarded: string[] = []
+  for (let index = 0; index < args.length; index += 1) {
+    const argument = args[index]
+    if (argument === '--engine') {
+      const value = args[index + 1]
+      if (!value || value.startsWith('--')) {
+        throw new Error('--engine must be one of official, legacy')
+      }
+      if (engine !== undefined && engine !== value) {
+        throw new Error('--engine must select exactly one of official, legacy')
+      }
+      engine = value
+      index += 1
+      continue
+    }
+    if (argument.startsWith('--engine=')) {
+      const value = argument.slice('--engine='.length)
+      if (engine !== undefined && engine !== value) {
+        throw new Error('--engine must select exactly one of official, legacy')
+      }
+      engine = value
+      continue
+    }
+    forwarded.push(argument)
+  }
+  if (engine !== undefined && engine !== 'official' && engine !== 'legacy') {
+    throw new Error(`--engine must be one of official, legacy; received ${engine}`)
+  }
+  return { engine: engine ?? 'official', args: forwarded }
+}
+
+function validateLegacyMetadata(args: string[]): void {
+  let raw: string | undefined
+  for (let index = 0; index < args.length; index += 1) {
+    if (args[index] === '--metadata') {
+      const value = args[index + 1]
+      if (!value || value.startsWith('--')) {
+        throw new Error('--metadata must be a JSON object')
+      }
+      raw = value
+      index += 1
+      continue
+    }
+    if (args[index].startsWith('--metadata=')) {
+      raw = args[index].slice('--metadata='.length)
+    }
+  }
+  let metadata: unknown = {}
+  if (raw !== undefined) {
+    try {
+      // The frozen legacy CLI hands this value directly to json.loads. Do not
+      // add @file/path expansion here: only reflection inputs support it.
+      metadata = JSON.parse(raw)
+    } catch {
+      throw new Error('--metadata must be a JSON object containing valid JSON')
+    }
+  }
+  if (typeof metadata !== 'object' || metadata === null || Array.isArray(metadata)) {
+    throw new Error('--metadata must be a JSON object')
+  }
+  // The frozen CLI consumes the original argv with json.loads. Keep the raw
+  // spelling so Python, not JavaScript, owns JSON number precision and adds
+  // the selected legacy-engine tag to the run metadata.
+}
+
+interface BooleanEnvironmentOption {
+  environment: string
+  value: string
+}
+
+// Parsing starts from an arbitrary command-line string. Keep the literal
+// tuples above checked, then widen only the map boundary used for lookup.
+const VALUE_OPTIONS_BY_FLAG: ReadonlyMap<string, EnvironmentOption> = new Map(
+  VALUE_OPTIONS.map(option => [option.flag, option])
+)
+const BOOLEAN_OPTIONS_BY_FLAG: ReadonlyMap<string, BooleanEnvironmentOption> = new Map(
+  BOOLEAN_OPTIONS.map(([flag, environment, value]) => [flag, { environment, value }])
+)
+const CONTROLLED_ENVIRONMENT_NAMES = new Set([
+  'ORIZU_PROJECT',
+  'ORIZU_METADATA',
+  ...VALUE_OPTIONS.map(option => option.environment),
+  ...BOOLEAN_OPTIONS.map(([, environment]) => environment),
+  'ORIZU_USE_MERGE',
+  'ORIZU_MAX_MERGE_INVOCATIONS',
+  'ORIZU_SAMPLING_STRATEGY',
+  'ORIZU_SELECTION_STRATEGY',
+  'ORIZU_MAX_PAYLOAD_CHARS',
+  'ORIZU_INSTRUCTION_SET_PROFILE_VERSION_ID',
+  // Candidate selection is an explicit opt-in.  Clearing it before option
+  // translation prevents an inherited environment from selecting a proposer
+  // on an otherwise byte-for-byte normal official-GEPA launch.
+  'ORIZU_CANDIDATE_PROPOSER',
+  'ORIZU_COMPONENT_SELECTOR',
+])
+
+function optionValueOrThrow(args: string[], index: number, flag: string, allowEmpty = false): { value: string; nextIndex: number } {
+  const argument = args[index]
+  const equalsPrefix = `${flag}=`
+  if (argument.startsWith(equalsPrefix)) {
+    const value = argument.slice(equalsPrefix.length)
+    if ((!allowEmpty && value === '') || value.startsWith('--')) {
+      throw new Error(`${flag} requires a value that does not start with --`)
+    }
+    return { value, nextIndex: index }
+  }
+
+  const value = args[index + 1]
+  if (value === undefined || value.startsWith('--')) {
+    throw new Error(`${flag} requires a value that does not start with --`)
+  }
+  return { value, nextIndex: index + 1 }
+}
+
+function translateOfficialOptions(args: string[], project: string, environment: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
+  const connectorEnvironment: NodeJS.ProcessEnv = { ...environment }
+  for (const name of CONTROLLED_ENVIRONMENT_NAMES) {
+    delete connectorEnvironment[name]
+  }
+  connectorEnvironment.ORIZU_PROJECT = project
+
+  let metadata: string | undefined
+  let hasInstructionSet = false
+  let hasCandidateVersion = false
+  const budgetFlags: string[] = []
+  for (let index = 0; index < args.length; index += 1) {
+    const argument = args[index]
+    if (!argument.startsWith('--')) {
+      throw new Error(`Unexpected run-gepa argument ${argument}`)
+    }
+
+    const flag = argument.includes('=') ? argument.slice(0, argument.indexOf('=')) : argument
+    if (flag === '--candidate-version-id') hasCandidateVersion = true
+    if (flag === '--project') {
+      const parsed = optionValueOrThrow(args, index, flag)
+      connectorEnvironment.ORIZU_PROJECT = parsed.value
+      index = parsed.nextIndex
+      continue
+    }
+    if (flag === '--metadata') {
+      const parsed = optionValueOrThrow(args, index, flag)
+      metadata = parsed.value
+      index = parsed.nextIndex
+      continue
+    }
+    if (flag === '--candidate-proposer') {
+      const parsed = optionValueOrThrow(args, index, flag)
+      if (parsed.value !== 'skilled-proposer') {
+        throw new Error('--candidate-proposer must be skilled-proposer')
+      }
+      connectorEnvironment.ORIZU_CANDIDATE_PROPOSER = parsed.value
+      index = parsed.nextIndex
+      continue
+    }
+    const option = VALUE_OPTIONS_BY_FLAG.get(flag)
+    if (option) {
+      const parsed = optionValueOrThrow(args, index, flag, option.allowEmpty)
+      if (flag === '--budget') {
+        if (!['auto', 'light', 'medium', 'heavy'].includes(parsed.value)) {
+          throw new Error('--budget must be one of auto, light, medium, heavy')
+        }
+        budgetFlags.push(flag)
+      }
+      if (['--max-metric-calls', '--max-full-evals', '--max-iterations', '--max-candidate-proposals'].includes(flag)) {
+        budgetFlags.push(flag)
+      }
+      if (flag === '--candidate-selection-strategy' && !['pareto', 'current_best', 'epsilon_greedy'].includes(parsed.value)) {
+        throw new Error('--candidate-selection-strategy must be one of pareto, current_best, epsilon_greedy')
+      }
+      if (flag === '--scorer-input-contract' && !['gepa', 'flat_row'].includes(parsed.value)) {
+        throw new Error('--scorer-input-contract must be one of gepa, flat_row')
+      }
+      connectorEnvironment[option.environment] = option.json
+        ? jsonObjectValue(parsed.value, option.flag)
+        : option.readFile ? textValue(parsed.value) : parsed.value
+      if (flag === '--instruction-set') hasInstructionSet = true
+      index = parsed.nextIndex
+      continue
+    }
+    if (flag === '--component-selector') {
+      const parsed = optionValueOrThrow(args, index, flag)
+      if (!['round-robin', 'all'].includes(parsed.value)) throw new Error('--component-selector must be one of round-robin, all')
+      connectorEnvironment.ORIZU_COMPONENT_SELECTOR = parsed.value.replace('-', '_')
+      index = parsed.nextIndex
+      continue
+    }
+    const boolean = BOOLEAN_OPTIONS_BY_FLAG.get(flag)
+    if (boolean) {
+      if (argument.includes('=')) {
+        throw new Error(`${flag} does not accept a value`)
+      }
+      if (args[index + 1] !== undefined && !args[index + 1].startsWith('--')) {
+        throw new Error(`${flag} does not accept a value`)
+      }
+      connectorEnvironment[boolean.environment] = boolean.value
+      continue
+    }
+    throw new Error(`Unknown run-gepa option ${flag}`)
+  }
+
+  if (budgetFlags.length > 1) {
+    throw new Error('Budget options are mutually exclusive; choose at most one of --budget, --max-metric-calls, --max-full-evals, --max-iterations, --max-candidate-proposals')
+  }
+  if (hasInstructionSet && hasCandidateVersion) throw new Error('--instruction-set and --candidate-version-id are mutually exclusive')
+  if (hasInstructionSet && connectorEnvironment.ORIZU_MODEL_CONFIG_IDENTITY === undefined) throw new Error('--instruction-set requires --model-config')
+  if (hasInstructionSet && connectorEnvironment.ORIZU_COMPONENT_SELECTOR === undefined) connectorEnvironment.ORIZU_COMPONENT_SELECTOR = 'round_robin'
+  if ((connectorEnvironment.ORIZU_PROPOSAL_MAX_CALLS !== undefined
+       || connectorEnvironment.ORIZU_PROPOSAL_MAX_TOKENS !== undefined)
+      && connectorEnvironment.ORIZU_CANDIDATE_PROPOSER !== 'skilled-proposer') {
+    throw new Error('--proposal-max-calls and --proposal-max-tokens require --candidate-proposer skilled-proposer')
+  }
+
+  const reflectionModel = connectorEnvironment.ORIZU_REFLECTION_MODEL ?? 'anthropic/claude-opus-4-7'
+  if (!reflectionModel.startsWith('openai/') && connectorEnvironment.ORIZU_REFLECTION_MAX_TOKENS === undefined) {
+    throw new Error('--reflection-max-tokens is required for Anthropic reflection models')
+  }
+
+  connectorEnvironment.ORIZU_METADATA = validatedMetadata(metadata)
+  return connectorEnvironment
+}
+
+function validatedMetadata(raw: string | undefined): string {
+  if (raw === undefined) return '{}'
+  try {
+    const value: unknown = JSON.parse(raw)
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) throw new Error()
+  } catch {
+    throw new Error('--metadata must be a JSON object containing valid JSON')
+  }
+  return raw
+}
+
+export function dispatchGepaEngine(args: string[], project: string, environment: NodeJS.ProcessEnv): GepaEngineDispatch {
+  const selected = removeEngine(args)
+  if (selected.engine === 'legacy') {
+    for (const flag of ['--instruction-set', '--model-config', '--component-selector', '--max-candidate-proposals', '--candidate-proposer', '--proposal-max-calls', '--proposal-max-tokens']) {
+      if (selected.args.some(argument => argument === flag || argument.startsWith(`${flag}=`))) {
+        throw new Error(`${flag} is supported by the official GEPA engine only`)
+      }
+    }
+    validateLegacyMetadata(selected.args)
+    return {
+      engine: 'legacy',
+      args: selected.args,
+      environment,
+      module: 'orizu_gepa.cli',
+    }
+  }
+
+  const connectorEnvironment = translateOfficialOptions(selected.args, project, environment)
+  return { engine: 'official', args: [], environment: connectorEnvironment, module: 'orizu_gepa_connector' }
+}

package/src/gepa-python-command.ts

@@ -0,0 +1,31 @@
+export interface GepaPythonCommand {
+  python: string
+  args: string[]
+}
+
+export function getGepaPythonCommand(args: string[], environment: NodeJS.ProcessEnv): GepaPythonCommand {
+  let python = environment.PYTHON || 'python3'
+  const forwarded: string[] = []
+  for (let index = 0; index < args.length; index += 1) {
+    const argument = args[index]
+    if (argument === '--python') {
+      const value = args[index + 1]
+      if (!value || value.startsWith('--')) {
+        throw new Error('--python requires a value that does not start with --')
+      }
+      python = value
+      index += 1
+      continue
+    }
+    if (argument.startsWith('--python=')) {
+      const value = argument.slice('--python='.length)
+      if (!value || value.startsWith('--')) {
+        throw new Error('--python requires a value that does not start with --')
+      }
+      python = value
+      continue
+    }
+    forwarded.push(argument)
+  }
+  return { python, args: forwarded }
+}

package/src/gepa-python-paths.ts

@@ -0,0 +1,56 @@
+import { existsSync } from 'fs'
+import { fileURLToPath } from 'url'
+
+import { isOrizuSourceCheckout } from '../scripts/orizu-source-checkout.mjs'
+
+function prefersLiveSource(): boolean {
+  // The source candidates belong to this monorepo only when the candidate
+  // root identifies itself as Orizu. A consumer's .git marker is not proof:
+  // npm installs commonly live inside another repository.
+  return isOrizuSourceCheckout(fileURLToPath(new URL('../../../package.json', import.meta.url)))
+}
+
+export function resolveGepaPythonPath(
+  candidates: string[],
+  pathExists: (candidate: string) => boolean = existsSync
+): string | null {
+  return candidates.find(pathExists) ?? null
+}
+
+export function bundledOrizuGepaPythonPath(): string | null {
+  const source = fileURLToPath(new URL('../../orizu-gepa-python/src', import.meta.url))
+  const vendor = fileURLToPath(new URL('../vendor/orizu-gepa-python/src', import.meta.url))
+  const candidates = prefersLiveSource() ? [source, vendor] : [vendor]
+
+  return resolveGepaPythonPath(candidates)
+}
+
+export function bundledOrizuGepaConnectorPythonPath(): string | null {
+  const source = fileURLToPath(new URL('../../orizu-gepa/src', import.meta.url))
+  const vendor = fileURLToPath(new URL('../vendor/orizu-gepa/src', import.meta.url))
+  const candidates = prefersLiveSource() ? [source, vendor] : [vendor]
+
+  return resolveGepaPythonPath(candidates)
+}
+
+export function bundledOfficialGepaPythonPath(): string | null {
+  const sourceArchive = fileURLToPath(new URL('../gepa-python-source.zip', import.meta.url))
+  const vendor = fileURLToPath(new URL('../vendor/gepa-python/src', import.meta.url))
+  // The checked-in pinned wheel is directly importable from PYTHONPATH in a
+  // source checkout. Published packages intentionally omit that archive and
+  // must resolve only the verified tree materialized by prepack.
+  const candidates = prefersLiveSource() ? [sourceArchive, vendor] : [vendor]
+
+  return resolveGepaPythonPath(candidates)
+}
+
+export function getGepaPythonPathEntries(existingPythonPath: string | undefined): string[] {
+  const pythonPathEntries = [
+    bundledOrizuGepaConnectorPythonPath(),
+    bundledOrizuGepaPythonPath(),
+    bundledOfficialGepaPythonPath(),
+    existingPythonPath,
+  ].filter((entry): entry is string => Boolean(entry))
+
+  return pythonPathEntries
+}

package/src/help.ts

@@ -35,6 +35,7 @@ const GROUPS: CliGroupDoc[] = [
   { name: 'Teams', summary: 'Manage teams and team memberships.' },
   { name: 'Projects', summary: 'Manage projects inside teams.' },
   { name: 'Prompts and judges', summary: 'Work with versioned prompt and judge artifacts.' },
+  { name: 'Instruction sets', summary: 'Inspect the project-scoped instruction-set control plane.' },
   { name: 'Report comments', summary: 'Review and mutate anchored report comments across prompt, optimization, and task reports.' },
   { name: 'Diff comments', summary: 'Export inline comments with recoverable prompt-diff context.' },
   { name: 'Scorers and runners', summary: 'Register scorers, push runnable artifacts, execute runners, and submit scores.' },
@@ -50,6 +51,44 @@ const GROUPS: CliGroupDoc[] = [
 ]
 
 export const COMMAND_DOCS: CliCommandDoc[] = [
+  { path: ['instructions', 'create'], aliases: [['instruction-sets', 'create']], usage: 'orizu instructions create <manifest> --project <team/project> [--runner-version <id>] [--model-config <identity>] [--json]', summary: 'Create an instruction set from a local manifest.', group: 'Instruction sets', options: [{ name: '--runner-version <id>', help: 'Pin the runner version for component prompt versions.' }, { name: '--model-config <identity>', help: 'Select the default model configuration.' }, { name: '--json', help: 'Print one JSON document.' }], examples: ['orizu instructions create ./orizu.instruction-set.json --project core/evals --model-config anthropic/claude-haiku'] },
+  { path: ['instructions', 'push'], aliases: [['instruction-sets', 'push']], usage: 'orizu instructions push <manifest> --project <team/project> [--set <slug-or-exact-name>] [--runner-version <id>] [--json]', summary: 'Push a new instruction-set profile version.', group: 'Instruction sets', options: [{ name: '--set <slug-or-exact-name>', help: 'Target the stable set handle when it differs from the manifest name.' }, { name: '--runner-version <id>', help: 'Pin the runner version for changed component prompt versions.' }, { name: '--json', help: 'Print one JSON document.' }], examples: ['orizu instructions push ./orizu.instruction-set.json --project core/evals --set planner'] },
+  {
+    path: ['instructions', 'list'],
+    aliases: [['instruction-sets', 'list']],
+    usage: 'orizu instructions list [--project <team/project>] [--status active|archived|all] [--json]',
+    summary: 'List instruction sets in a project.',
+    group: 'Instruction sets',
+    options: [{ name: '--project <team/project>', help: 'Project slug (defaults to configured context).' }, { name: '--status <active|archived|all>', help: 'Filter archived instruction sets.' }, { name: '--json', help: 'Print JSON.' }],
+    examples: ['orizu instructions list --project core/evals', 'orizu instructions list --status archived --json'],
+  },
+  {
+    path: ['instructions', 'show'],
+    aliases: [['instruction-sets', 'show']],
+    usage: 'orizu instructions show <set> [--project <team/project>] [--status active|archived|all] [--json]',
+    summary: 'Show an instruction set shape, default, and profile production state.',
+    group: 'Instruction sets',
+    options: [{ name: '--project <team/project>', help: 'Project slug (defaults to configured context).' }, { name: '--status <active|archived|all>', help: 'Filter archived instruction sets.' }, { name: '--json', help: 'Print JSON.' }],
+    examples: ['orizu instructions show research --project core/evals', 'orizu instructions show research --json'],
+  },
+  { path: ['instructions', 'profiles', 'new'], aliases: [['instruction-sets', 'profiles', 'new']], usage: 'orizu instructions profiles new <set> --project <team/project> --model-config <identity> [--json]', summary: 'Create a model-config profile seeded from the instruction-set default.', group: 'Instruction sets', options: [{ name: '--model-config <identity>', help: 'Model config identity for the new profile.', required: true }, { name: '--json', help: 'Print JSON.' }], examples: ['orizu instructions profiles new planner --project core/evals --model-config anthropic/claude-haiku'] },
+  { path: ['instructions', 'profiles', 'promote'], aliases: [['instruction-sets', 'profiles', 'promote']], usage: 'orizu instructions profiles promote <set> --project <team/project> --model-config <identity> --version <n> [--json]', summary: 'Move one profile version to production.', group: 'Instruction sets', options: [{ name: '--model-config <identity>', help: 'Profile model config.', required: true }, { name: '--version <n>', help: 'Profile version to promote.', required: true }, { name: '--json', help: 'Print JSON.' }], examples: ['orizu instructions profiles promote planner --project core/evals --model-config anthropic/claude-haiku --version 2'] },
+  { path: ['instructions', 'profiles', 'rollback'], aliases: [['instruction-sets', 'profiles', 'rollback']], usage: 'orizu instructions profiles rollback <set> --project <team/project> --model-config <identity> --to <n> [--json]', summary: 'Create a rollback version and move profile production to it.', group: 'Instruction sets', options: [{ name: '--model-config <identity>', help: 'Profile model config.', required: true }, { name: '--to <n>', help: 'Historical profile version to copy.', required: true }, { name: '--json', help: 'Print JSON.' }], examples: ['orizu instructions profiles rollback planner --project core/evals --model-config anthropic/claude-haiku --to 1'] },
+  { path: ['instructions', 'default', 'show'], aliases: [['instruction-sets', 'default', 'show']], usage: 'orizu instructions default show <set> --project <team/project> [--json]', summary: 'Show the instruction-set default and its resolution impact.', group: 'Instruction sets', options: [{ name: '--project <team/project>', help: 'Project slug.', required: true }, { name: '--json', help: 'Print JSON.' }], examples: ['orizu instructions default show planner --project core/evals'] },
+  { path: ['instructions', 'default', 'move'], aliases: [['instruction-sets', 'default', 'move']], usage: 'orizu instructions default move <set> --project <team/project> --model-config <identity> --version <n> [--json]', summary: 'Move the instruction-set default to a profile version.', group: 'Instruction sets', options: [{ name: '--project <team/project>', help: 'Project slug.', required: true }, { name: '--model-config <identity>', help: 'Target model config.', required: true }, { name: '--version <n>', help: 'Target profile version.', required: true }, { name: '--json', help: 'Print JSON.' }], examples: ['orizu instructions default move planner --project core/evals --model-config anthropic/claude-haiku --version 2'] },
+  { path: ['instructions', 'shape', 'add'], aliases: [['instruction-sets', 'shape', 'add']], usage: 'orizu instructions shape add <set> --project <team/project> --key <key> --from <manifest> [--json]', summary: 'Add one component key to every instruction-set profile.', group: 'Instruction sets', options: [{ name: '--project <team/project>', help: 'Project slug.', required: true }, { name: '--key <key>', help: 'Component key to add.', required: true }, { name: '--from <manifest>', help: 'Manifest containing the component body.', required: true }, { name: '--json', help: 'Print JSON.' }], examples: ['orizu instructions shape add planner --project core/evals --key skill --from planner.json'] },
+  { path: ['instructions', 'shape', 'remove'], aliases: [['instruction-sets', 'shape', 'remove']], usage: 'orizu instructions shape remove <set> --project <team/project> --key <key> [--json]', summary: 'Remove one component key from every instruction-set profile.', group: 'Instruction sets', options: [{ name: '--project <team/project>', help: 'Project slug.', required: true }, { name: '--key <key>', help: 'Component key to remove.', required: true }, { name: '--json', help: 'Print JSON.' }], examples: ['orizu instructions shape remove planner --project core/evals --key skill'] },
+  {
+    path: ['instructions', 'sync'],
+    aliases: [['instruction-sets', 'sync']],
+    usage: 'orizu instructions sync <set> --out <dir> [--model-config <identity>] [--project <team/project>] [--json]',
+    summary: 'Write an instruction set for offline runner loading.',
+    group: 'Instruction sets',
+    options: [{ name: '--out <dir>', help: 'Destination parent directory.', required: true }, { name: '--model-config <identity>', help: 'Sync only one profile plus default.' }, { name: '--project <team/project>', help: 'Project slug.' }, { name: '--json', help: 'Print source transport JSON.' }],
+    examples: ['orizu instructions sync planner --out ./instructions --project core/evals'],
+  },
+  { path: ['instructions', 'archive'], aliases: [['instruction-sets', 'archive']], usage: 'orizu instructions archive <slug-or-exact-name> --project <team/project> [--json]', summary: 'Archive an instruction set without changing resolution or sync.', group: 'Instruction sets', options: [{ name: '--project <team/project>', help: 'Project slug.', required: true }, { name: '--json', help: 'Print JSON.' }], examples: ['orizu instructions archive planner --project core/evals'] },
+  { path: ['instructions', 'restore'], aliases: [['instruction-sets', 'restore']], usage: 'orizu instructions restore <slug-or-exact-name> --project <team/project> [--json]', summary: 'Restore an archived instruction set.', group: 'Instruction sets', options: [{ name: '--project <team/project>', help: 'Project slug.', required: true }, { name: '--json', help: 'Print JSON.' }], examples: ['orizu instructions restore planner --project core/evals'] },
   {
     path: ['login'],
     usage: 'orizu login [--no-prompt-if-logged-in]',
@@ -342,39 +381,21 @@ export const COMMAND_DOCS: CliCommandDoc[] = [
     summary: 'List prompt artifacts in a project.',
     group: 'Prompts and judges',
   },
-  {
-    path: ['prompts', 'archive'],
-    usage: 'orizu prompts archive <prompt-id-or-name> --project <team/project> [--json]',
-    summary: 'Mark a prompt artifact as archived.',
-    group: 'Prompts and judges',
-  },
-  {
-    path: ['prompts', 'restore'],
-    usage: 'orizu prompts restore <prompt-id-or-name> --project <team/project> [--json]',
-    summary: 'Restore an archived prompt artifact to active status.',
-    group: 'Prompts and judges',
-  },
   {
     path: ['prompts', 'pull'],
     usage: 'orizu prompts pull <prompt-id-or-name> --project <team/project> --out <dir> [--label <label> | --version <id>] [--json]',
     summary: 'Pull a prompt artifact version to a local directory.',
     group: 'Prompts and judges',
   },
-  {
-    path: ['prompts', 'push'],
-    usage: 'orizu prompts push <dir> [--runner-version <id>] [--project <team/project>] [--parent <version-id>] [--session <session-id>] [--report-file <path>] [--json]',
-    summary: 'Push a local prompt artifact directory as a new version (with --session: a commit-first git draft).',
-    group: 'Prompts and judges',
-  },
   {
     path: ['prompts', 'report', 'set'],
-    usage: 'orizu prompts report set --prompt <id-or-name> --project <team/project> (--version <n> | --version-id <id>) (--report <markdown|@file> | --report-file <path>) [--json]',
+    usage: 'orizu prompts report set --prompt <id-or-name> [--project <team/project>] (--version <n> | --version-id <id>) (--report <markdown|@file> | --report-file <path>) [--json]',
     summary: 'Upload or replace the Markdown report for one explicit prompt version.',
     group: 'Prompts and judges',
     aliases: [['prompts', 'report', 'upload']],
     options: [
       { name: '--prompt <id-or-name>', help: 'Prompt ID or name.', required: true },
-      { name: '--project <team/project>', help: 'Project slug containing the prompt.', required: true },
+      { name: '--project <team/project>', help: 'Project slug containing the prompt.' },
       { name: '--version <n>', help: 'Positive prompt version number.' },
       { name: '--version-id <id>', help: 'Explicit prompt version ID.' },
       { name: '--report <markdown|@file>', help: 'Inline Markdown or an @file reference.' },
@@ -389,7 +410,7 @@ export const COMMAND_DOCS: CliCommandDoc[] = [
   {
     path: ['prompts', 'labels', 'set'],
     usage: 'orizu prompts labels set <prompt-name> <label> --version <version-id> [--project <team/project>] [--json]',
-    summary: 'Move or set a prompt label to a version.',
+    summary: 'Move or set a non-production prompt label; use instructions profiles promote for production.',
     group: 'Prompts and judges',
   },
   {
@@ -464,6 +485,12 @@ export const COMMAND_DOCS: CliCommandDoc[] = [
     summary: 'Execute a scorer locally for a prompt version or optimization candidate.',
     group: 'Scorers and runners',
   },
+  {
+    path: ['scorers', 'verify-parity'],
+    usage: 'orizu scorers verify-parity --scorer-version <id> --dataset-version <id> --split-set <id> [--split <name>] --outputs <outputs.jsonl> --original <module:function> [--scorer-input-contract gepa|flat_row] [--scorer-candidate-field <row-field>] [--runner-dir <dir>] [--python <cmd>] [--tolerance <float>] [--limit <n>] [--json]',
+    summary: 'Prove a migrated scorer runner scores rows the same as the original Python metric.',
+    group: 'Scorers and runners',
+  },
   {
     path: ['scores', 'submit'],
     usage: 'orizu scores submit <results.jsonl|results.json> --scorer-version <id> (--subject-version <prompt-version-id> | --optimization-run <id> --candidate <id>) [--aggregate] [--dataset-version <id> --split-set <id> --split <name>] [--project <team/project>] [--json]',
@@ -536,6 +563,7 @@ export const COMMAND_DOCS: CliCommandDoc[] = [
     summary: 'List optimization runs with explicit archive visibility.',
     group: 'Optimizations',
   },
+  { path: ['optimizations', 'promote'], usage: 'orizu optimizations promote <run-id> --candidate <id> [--label production] [--project <team/project>] [--json]', summary: 'Promote a selected optimization candidate.', group: 'Optimizations', options: [{ name: '--candidate <id>', help: 'Candidate to promote.', required: true }, { name: '--label production', help: 'Move the new tuple profile version to production.' }, { name: '--project <team/project>', help: 'Project slug (defaults to configured context).' }, { name: '--json', help: 'Print JSON.' }], examples: ['orizu optimizations promote <run-id> --candidate candidate-2 --label production'] },
   {
     path: ['optimizations', 'archive'],
     usage: 'orizu optimizations archive <run-id> [--project <team/project>] [--json]',
@@ -550,8 +578,8 @@ export const COMMAND_DOCS: CliCommandDoc[] = [
   },
   {
     path: ['optimizations', 'run-gepa'],
-    usage: 'orizu optimizations run-gepa --project <team/project> --optimizer-version-id <id> --candidate-version-id <id> --runner-version-id <id> --candidate-runner-dir <dir> --scorer-version-id <id> --scorer-runner-version-id <id> --scorer-runner-dir <dir> [--scorer-input-contract gepa|flat_row] [--scorer-candidate-field <row-field>] [--allow-degenerate-seed] --dataset-version-id <id> --split-set-id <id> [--train-split train] [--val-split validation] [--budget auto|light|medium|heavy | --max-metric-calls <n> | --max-full-evals <n> | --max-iterations <n>] [--num-threads auto|N] [--reflection-retry-attempts N] [--reflection-http-timeout-seconds N] [--log-dir logs]',
-    summary: 'Run the bundled GEPA-style optimizer locally and stream events. Validates the scorer contract on the seed before iterating; judge runners built for flat-row score runs need --scorer-input-contract flat_row (ALI-1158).',
+    usage: 'orizu optimizations run-gepa --project <team/project> --optimizer-version-id <id> (--candidate-version-id <id> | --instruction-set <name> --model-config <identity> [--component-selector round-robin|all]) --runner-version-id <id> --candidate-runner-dir <dir> --scorer-version-id <id> --scorer-runner-version-id <id> --scorer-runner-dir <dir> [--engine official|legacy] [--scorer-input-contract gepa|flat_row] [--scorer-candidate-field <row-field>] [--allow-degenerate-seed] --dataset-version-id <id> --split-set-id <id> [--train-split train] [--val-split validation] [--budget auto|light|medium|heavy | --max-metric-calls <n> | --max-full-evals <n> | --max-iterations <n> | --max-candidate-proposals <n>] [--num-threads auto|N] [--reflection-retry-attempts N] [--reflection-http-timeout-seconds N] [--log-dir logs]',
+    summary: 'Run official GEPA locally and stream events; pass --engine legacy only for the frozen safety hatch. --instruction-set requires --model-config and cannot be combined with --candidate-version-id; round-robin updates one component-map entry per round and all updates every component. --max-candidate-proposals is official-engine-only. Validates the scorer contract on the seed before iterating; judge runners built for flat-row score runs need --scorer-input-contract flat_row (ALI-1158).',
     group: 'Optimizations',
   },
   {
@@ -1057,6 +1085,46 @@ export const COMMAND_DOCS: CliCommandDoc[] = [
     ],
     examples: ['orizu connectors', 'orizu connectors status --project highlight/hip --json'],
   },
+  {
+    path: ['model-configs', 'create'],
+    usage: 'orizu model-configs create <provider/model> [--settings <json|@file>] [--name <name>] [--project <team/project>] [--json]',
+    summary: 'Create a provider-qualified model config with its first settings version.',
+    group: 'Model configs',
+    options: [{ name: '--settings <json|@file>', help: 'Optional JSON settings object or a JSON file; defaults to {}.' }, { name: '--name <name>', help: 'Optional display name.' }, { name: '--project <team/project>', help: 'Project that owns the config.' }, { name: '--json', help: 'Emit the machine-readable model config.' }],
+    examples: ['orizu model-configs create azure/gpt-5.4-mini --settings @settings.json'],
+  },
+  {
+    path: ['model-configs', 'list'],
+    usage: 'orizu model-configs list [--project <team/project>] [--json]',
+    summary: 'List model configs for a project.',
+    group: 'Model configs',
+    options: [{ name: '--project <team/project>', help: 'Project whose configs to list.' }, { name: '--json', help: 'Emit machine-readable model configs.' }],
+    examples: ['orizu model-configs list --project core/evals --json'],
+  },
+  {
+    path: ['model-configs', 'show'],
+    usage: 'orizu model-configs show <provider/model> [--project <team/project>] [--json]',
+    summary: 'Show a model config and its current settings version.',
+    group: 'Model configs',
+    options: [{ name: '--project <team/project>', help: 'Project that owns the config.' }, { name: '--json', help: 'Emit the machine-readable model config.' }],
+    examples: ['orizu model-configs show openai/gpt-5.4-mini'],
+  },
+  {
+    path: ['model-configs', 'settings', 'set'],
+    usage: 'orizu model-configs settings set <provider/model> --settings <json|@file> [--project <team/project>] [--json]',
+    summary: 'Add a settings version and advance the config current pointer.',
+    group: 'Model configs',
+    options: [{ name: '--settings <json|@file>', help: 'JSON settings object or a JSON file.', required: true }, { name: '--project <team/project>', help: 'Project that owns the config.' }, { name: '--json', help: 'Emit the machine-readable model config.' }],
+    examples: ["orizu model-configs settings set openai/gpt-5.4-mini --settings '{\"temperature\":0.2}'"],
+  },
+  {
+    path: ['model-configs', 'copy'],
+    usage: 'orizu model-configs copy <provider/model> --to <provider/model> [--project <team/project>] [--json]',
+    summary: 'Copy the current settings snapshot to a new provider-qualified config.',
+    group: 'Model configs',
+    options: [{ name: '--to <provider/model>', help: 'New provider-qualified config identity.', required: true }, { name: '--project <team/project>', help: 'Project that owns the config.' }, { name: '--json', help: 'Emit the machine-readable model config.' }],
+    examples: ['orizu model-configs copy openai/gpt-5.4-mini --to azure/gpt-5.4-mini'],
+  },
   {
     path: ['manifests', 'list'],
     usage: 'orizu manifests list [--project <team/project>] [--status <status>] [--json]',
@@ -1133,8 +1201,10 @@ export function commandDocsWithPrefix(args: string[]): CliCommandDoc[] {
   }
 
   return COMMAND_DOCS.filter(doc =>
-    args.every((part, index) => doc.path[index] === part) &&
-    doc.path.length > args.length
+    [doc.path, ...(doc.aliases || [])].some(path =>
+      args.every((part, index) => path[index] === part) &&
+      path.length > args.length
+    )
   )
 }