orizu 0.5.20 → 0.5.21

package/scripts/refresh-skilled-proposer-lock.mjs

@@ -0,0 +1,256 @@
+#!/usr/bin/env node
+
+import { createHash, randomUUID } from "node:crypto";
+import { execFileSync } from "node:child_process";
+import {
+  closeSync,
+  fsyncSync,
+  mkdtempSync,
+  openSync,
+  readFileSync,
+  readdirSync,
+  renameSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const scriptDirectory = dirname(fileURLToPath(import.meta.url));
+const cliRoot = resolve(scriptDirectory, "..");
+const repositoryRoot = resolve(cliRoot, "../..");
+const inputPath = join(cliRoot, "requirements", "skilled-proposer.in");
+const lockPath = join(cliRoot, "requirements", "skilled-proposer.lock");
+
+const TARGETS = [
+  { name: "macos-arm64", platforms: ["macosx_15_0_arm64"] },
+  {
+    name: "linux-x86_64",
+    platforms: ["manylinux_2_28_x86_64", "manylinux2014_x86_64"],
+  },
+];
+const PYTHON_MINORS = ["3.10", "3.11", "3.12", "3.13", "3.14"];
+
+function parseArguments(argv) {
+  const options = {
+    check: false,
+    download: false,
+    python: join(repositoryRoot, ".scratch-deps", "venv", "bin", "python"),
+    wheelRoot: join(repositoryRoot, ".scratch-deps", "wheels"),
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const argument = argv[index];
+    if (argument === "--check") options.check = true;
+    else if (argument === "--download") options.download = true;
+    else if (argument === "--python") options.python = resolve(argv[++index]);
+    else if (argument === "--wheel-root") options.wheelRoot = resolve(argv[++index]);
+    else throw new Error(`Unknown argument: ${argument}`);
+  }
+  if (options.check && options.download) {
+    throw new Error("--check and --download are mutually exclusive");
+  }
+  return options;
+}
+
+function canonicalizeName(name) {
+  return name.toLowerCase().replace(/[._-]+/g, "-");
+}
+
+function parsePins() {
+  return readFileSync(inputPath, "utf8")
+    .split(/\r?\n/u)
+    .map((line) => line.trim())
+    .filter((line) => line && !line.startsWith("#"))
+    .map((line) => {
+      const match = /^([A-Za-z0-9._-]+)==([^ ;]+)(?:\s*;\s*(.+))?$/u.exec(line);
+      if (!match) throw new Error(`Invalid fully pinned requirement: ${line}`);
+      return {
+        name: canonicalizeName(match[1]),
+        version: match[2],
+        marker: match[3] ?? null,
+        source: line,
+      };
+    });
+}
+
+function pinApplies(pin, pythonMinor) {
+  if (!pin.marker) return true;
+  if (pin.marker === 'python_version == "3.10"') return pythonMinor === "3.10";
+  if (pin.marker === 'python_version >= "3.11" and python_version < "3.15"') {
+    return pythonMinor !== "3.10";
+  }
+  throw new Error(`Unsupported environment marker in ${pin.source}`);
+}
+
+function activePins(pins, pythonMinor) {
+  const active = pins.filter((pin) => pinApplies(pin, pythonMinor));
+  const names = new Set(active.map((pin) => pin.name));
+  const expectedCount = pythonMinor === "3.10" ? 60 : 58;
+  if (active.length !== expectedCount || names.size !== expectedCount) {
+    throw new Error(
+      `Expected ${expectedCount} unique active pins for Python ${pythonMinor}; found ${active.length}`,
+    );
+  }
+  return active;
+}
+
+function wheelIdentity(filename) {
+  const match = /^(.+?)-([^-]+)-[^-]+-[^-]+-[^-]+\.whl$/u.exec(filename);
+  if (!match) throw new Error(`Not a wheel filename: ${filename}`);
+  return { name: canonicalizeName(match[1]), version: match[2] };
+}
+
+function downloadWheelhouse(options, target, pythonMinor, pins) {
+  const wheelhouse = join(
+    options.wheelRoot,
+    `${target.name}-py${pythonMinor.replace(".", "")}`,
+  );
+  const temporary = mkdtempSync(join(tmpdir(), "orizu-ali-1505-pins-"));
+  const requirements = join(temporary, "requirements.txt");
+  writeFileSync(
+    requirements,
+    `${activePins(pins, pythonMinor)
+      .map(({ name, version }) => `${name}==${version}`)
+      .join("\n")}\n`,
+  );
+  const pipArguments = [
+    "-m",
+    "pip",
+    "download",
+    "--disable-pip-version-check",
+    "--no-deps",
+    "--only-binary=:all:",
+    "--implementation",
+    "cp",
+    "--python-version",
+    pythonMinor.replace(".", ""),
+    "--abi",
+    `cp${pythonMinor.replace(".", "")}`,
+  ];
+  for (const platform of target.platforms) {
+    pipArguments.push("--platform", platform);
+  }
+  pipArguments.push("--dest", wheelhouse, "--requirement", requirements);
+  try {
+    execFileSync(options.python, pipArguments, { stdio: "inherit", timeout: 10 * 60 * 1000 });
+  } finally {
+    rmSync(temporary, { recursive: true, force: true });
+  }
+}
+
+function digestWheel(path) {
+  return createHash("sha256").update(readFileSync(path)).digest("hex");
+}
+
+function collectWheelHashes(options, pins) {
+  const hashes = new Map(pins.map((pin) => [pin.source, new Set()]));
+
+  for (const target of TARGETS) {
+    for (const pythonMinor of PYTHON_MINORS) {
+      const active = activePins(pins, pythonMinor);
+      const activeByIdentity = new Map(
+        active.map((pin) => [`${pin.name}==${pin.version}`, pin]),
+      );
+      const wheelhouse = join(
+        options.wheelRoot,
+        `${target.name}-py${pythonMinor.replace(".", "")}`,
+      );
+      const files = readdirSync(wheelhouse).filter((file) => file.endsWith(".whl"));
+      const found = new Set();
+      for (const file of files) {
+        const identity = wheelIdentity(file);
+        const key = `${identity.name}==${identity.version}`;
+        const pin = activeByIdentity.get(key);
+        if (!pin) throw new Error(`Unexpected wheel in ${wheelhouse}: ${file}`);
+        if (found.has(pin.name)) {
+          throw new Error(`Multiple wheels for ${pin.name} in ${wheelhouse}`);
+        }
+        found.add(pin.name);
+        hashes.get(pin.source).add(digestWheel(join(wheelhouse, file)));
+      }
+      const missing = active.filter((pin) => !found.has(pin.name));
+      if (missing.length > 0) {
+        throw new Error(
+          `Missing wheels in ${wheelhouse}: ${missing.map((pin) => pin.source).join(", ")}`,
+        );
+      }
+    }
+  }
+  return hashes;
+}
+
+function renderLock(pins, hashes) {
+  const header = [
+    "# Generated by packages/cli/scripts/refresh-skilled-proposer-lock.mjs.",
+    "# Do not edit by hand; see packages/cli/requirements/README.md.",
+    "#",
+    "# Wheel-only coverage: CPython 3.10-3.14 on macOS 15+ arm64 and",
+    "# glibc-based Linux x86_64 compatible with the locked manylinux wheels.",
+    "# Other OS/architecture/libc combinations are intentionally not covered.",
+    "",
+  ];
+  const continuation = ` ${String.fromCharCode(92, 10)}`;
+  const requirements = [...pins]
+    .sort((left, right) => left.source.localeCompare(right.source))
+    .map((pin) => {
+      const pinHashes = [...hashes.get(pin.source)].sort();
+      if (pinHashes.length === 0) throw new Error(`No wheel hash for ${pin.source}`);
+      const hashLines = pinHashes
+        .map((hash) => `    --hash=sha256:${hash}`)
+        .join(continuation);
+      return pin.source + continuation + hashLines;
+    });
+  return `${header.join("\n")}${requirements.join("\n")}\n`;
+}
+
+function main() {
+  const options = parseArguments(process.argv.slice(2));
+  const pins = parsePins();
+  if (options.download) {
+    for (const target of TARGETS) {
+      for (const pythonMinor of PYTHON_MINORS) {
+        downloadWheelhouse(options, target, pythonMinor, pins);
+      }
+    }
+  }
+  const lock = renderLock(pins, collectWheelHashes(options, pins));
+  if (options.check) {
+    if (readFileSync(lockPath, "utf8") !== lock) {
+      throw new Error(`${lockPath} is stale; regenerate it from verified wheelhouses`);
+    }
+    process.stdout.write(`Verified ${lockPath}\n`);
+    return;
+  }
+  const temporaryLock = join(
+    dirname(lockPath),
+    `.skilled-proposer.lock-${process.pid}-${randomUUID()}.tmp`,
+  );
+  try {
+    const temporaryDescriptor = openSync(temporaryLock, "wx");
+    try {
+      writeFileSync(temporaryDescriptor, lock);
+      fsyncSync(temporaryDescriptor);
+    } finally {
+      closeSync(temporaryDescriptor);
+    }
+    renameSync(temporaryLock, lockPath);
+    const requirementsDescriptor = openSync(dirname(lockPath), "r");
+    try {
+      fsyncSync(requirementsDescriptor);
+    } finally {
+      closeSync(requirementsDescriptor);
+    }
+  } finally {
+    rmSync(temporaryLock, { force: true });
+  }
+  process.stdout.write(`Wrote ${lockPath}\n`);
+}
+
+try {
+  main();
+} catch (error) {
+  process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+  process.exitCode = 1;
+}

package/src/diff-comments-cli.ts

@@ -36,6 +36,7 @@ interface DiffCommentPayloadComment {
   body: string
   author: DiffCommentAuthor
   createdAt: string
+  componentKey?: string | null
   anchor: { side: 'old' | 'new'; line: number }
   context: {
     lineText: string
@@ -364,6 +365,9 @@ function printDiffComments(ctx: DiffCommentsCliContext, payload: DiffCommentsPay
         `${sanitizeHumanInlineText(ctx.sanitizeTerminalText, String(comment.anchor.line + 1))}`
       )
       printHumanTextBlock(ctx, comment.body)
+      if (typeof comment.componentKey === 'string' && comment.componentKey) {
+        ctx.printLine(`    Component: ${sanitizeHumanInlineText(ctx.sanitizeTerminalText, comment.componentKey)}`)
+      }
 
       if (comment.contextUnavailableReason) {
         ctx.printLine(

package/src/gepa-engine-dispatch.ts

@@ -34,6 +34,8 @@ const VALUE_OPTIONS: EnvironmentOption[] = [
   { 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' },
@@ -51,6 +53,8 @@ const VALUE_OPTIONS: EnvironmentOption[] = [
   { 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 = [
@@ -170,6 +174,12 @@ const CONTROLLED_ENVIRONMENT_NAMES = new Set([
   '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 } {
@@ -198,6 +208,8 @@ function translateOfficialOptions(args: string[], project: string, environment:
   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]
@@ -206,6 +218,7 @@ function translateOfficialOptions(args: string[], project: string, environment:
     }
 
     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
@@ -218,6 +231,15 @@ function translateOfficialOptions(args: string[], project: string, environment:
       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)
@@ -239,6 +261,14 @@ function translateOfficialOptions(args: string[], project: string, environment:
       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
     }
@@ -259,6 +289,14 @@ function translateOfficialOptions(args: string[], project: string, environment:
   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) {
@@ -283,8 +321,10 @@ function validatedMetadata(raw: string | undefined): string {
 export function dispatchGepaEngine(args: string[], project: string, environment: NodeJS.ProcessEnv): GepaEngineDispatch {
   const selected = removeEngine(args)
   if (selected.engine === 'legacy') {
-    if (selected.args.some(argument => argument === '--max-candidate-proposals' || argument.startsWith('--max-candidate-proposals='))) {
-      throw new Error('--max-candidate-proposals is supported by the official GEPA engine only')
+    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 {

package/src/gepa-python-paths.ts

@@ -34,9 +34,12 @@ export function bundledOrizuGepaConnectorPythonPath(): string | null {
 }
 
 export function bundledOfficialGepaPythonPath(): string | null {
-  const candidates = [
-    fileURLToPath(new URL('../vendor/gepa-python/src', import.meta.url)),
-  ]
+  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)
 }

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,30 +381,12 @@ 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]',
@@ -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> [--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. --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).',
+    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
+    )
   )
 }