orizu 0.5.21 → 0.5.23

package/vendor/skills/orizu-cli/references/prompt-control-plane.md

@@ -1,6 +1,6 @@
-# Prompt Control Plane
+# Instruction Control Plane
 
-Use this reference for the Phase 0 prompt, judge, scorer, runner, score, run, and optimization event control plane. These commands are for coding agents that need to push local artifacts into Orizu, run them locally, submit scores, and stream optimization progress back to the platform.
+Use this reference for the Phase 0 instruction, judge, scorer, runner, score, run, and optimization event control plane. Follow the [Authority map](../SKILL.md#authority-map) before executing its command sequences.
 
 ## Contents
 
@@ -16,14 +16,14 @@ Use this reference for the Phase 0 prompt, judge, scorer, runner, score, run, an
 1. Verify auth: `orizu --local whoami`.
 2. Export API context for scripts: `eval "$(orizu --local env --project <team>/<project>)"`.
 3. Create immutable dataset versions before creating splits.
-4. Push runners before prompts, judges, or prompt-runner scorers; prompt versions pin runner versions.
-5. Register scorers after their backing prompt/runner exists, then bind headline/tracked scorers to prompts when the UI should show those metrics.
+4. Push runners before instruction-set mutations, judges, or prompt-runner scorers; instruction components pin runner versions. Follow the Authority map after the runner version exists.
+5. Register scorers after their backing judge prompt/runner exists, then bind headline/tracked scorers to instruction components when the UI should show those metrics.
 6. Use `runners exec` to prove the runner contract locally before submitting runs or score runs.
 7. For common text-candidate optimization, prefer `orizu optimizations run-gepa`; it starts the run and logs events for you.
 8. After `run-gepa`, inspect `logs/<optimization_run_id>` first; it is the complete local trace for coding-agent analysis.
 9. Use `orizu optimizations export <run-id> --out <run-id>.optimization.json` when the local log is missing or the run happened elsewhere.
-10. Promote an accepted candidate with `orizu optimizations promote <run-id> --candidate <id> [--label production]`; tuple output reports its profile version and each component as changed or carried.
-11. Write and attach a markdown report for finished, failed, or cancelled runs; use `optimization-reports.md` for structure and diagnostic guidance.
+10. Write and attach a markdown report for finished, failed, or cancelled runs; use `optimization-reports.md` for structure and diagnostic guidance.
+11. Follow the [Authority map](../SKILL.md#authority-map). Simpler one-shot path: after the human accepts the report, a human curator runs `orizu optimizations promote <run-id> --candidate <id> --label production --project <team/project>`, materializing and labeling once. Equivalent two-stage path: an agent runs `orizu optimizations promote <run-id> --candidate <id> --project <team/project>` after acceptance. A human curator re-runs the same promotion as `orizu optimizations promote <run-id> --candidate <id> --label production --project <team/project>`. The idempotent finalizer finds the exact existing materialized version by run and candidate provenance, moves production, and creates no duplicate profile version or candidate-promoted event.
 12. For custom optimizers, start an optimization run before local execution, then stream events into that run.
 13. Use bare HTTP for optimization events; use `orizu log` only as a shell fallback.
 14. Promote only accepted candidates; rejected candidates stay in optimization events.
@@ -32,59 +32,75 @@ Customer model-provider secrets stay local. Do not upload Anthropic/OpenAI/etc.
 
 ## Instruction sets
 
-An instruction set is a set of named components (key → text); order carries no meaning.
-It has one profile per model config. Existing prompts appear as sets of one component. Inspect or
-write them with:
+Work within the fixed, ordered component shape and model-config profiles defined
+for instruction sets in Vocabulary. Existing prompts appear as one-component
+sets. Inspect or write them with the customer-facing `orizu instructions`
+namespace. Follow the [Authority map](../SKILL.md#authority-map) for mutation
+custody before copying a command:
 
 ```bash
-orizu instruction-sets list --project core/evals --status active --json
-orizu instruction-sets show planner --project core/evals --status active --json
-orizu instruction-sets create ./orizu.instruction-set.json --project core/evals --model-config anthropic/claude-haiku
-orizu instruction-sets push ./orizu.instruction-set.json --project core/evals
-orizu instruction-sets profiles new planner --project core/evals --model-config anthropic/claude-haiku
-orizu instruction-sets profiles promote planner --project core/evals --model-config anthropic/claude-haiku --version 2
-orizu instruction-sets profiles rollback planner --project core/evals --model-config anthropic/claude-haiku --to 1
-orizu instruction-sets default show planner --project core/evals
-orizu instruction-sets default move planner --project core/evals --model-config anthropic/claude-haiku --version 2
-orizu instruction-sets shape add planner --project core/evals --key safety --from ./orizu.instruction-set.json
-orizu instruction-sets shape remove planner --project core/evals --key safety
+orizu instructions list --project core/evals --status active --json
+orizu instructions show planner --project core/evals --status active --json
+orizu instructions create ./orizu.instruction-set.json --project core/evals --model-config anthropic/claude-haiku
+orizu instructions push ./orizu.instruction-set.json --project core/evals --set planner
+orizu instructions profiles new planner --project core/evals --model-config anthropic/claude-haiku
+orizu instructions profiles promote planner --project core/evals --model-config anthropic/claude-haiku --version 2
+orizu instructions profiles rollback planner --project core/evals --model-config anthropic/claude-haiku --to 1
+orizu instructions default show planner --project core/evals
+orizu instructions default move planner --project core/evals --model-config anthropic/claude-haiku --version 2
+orizu instructions shape add planner --project core/evals --key safety --from ./orizu.instruction-set.json
+orizu instructions shape remove planner --project core/evals --key safety
+orizu instructions archive planner --project core/evals --json
+orizu instructions restore planner --project core/evals --json
 ```
 
-The manifest contains `name`, `shape` (the set of component keys; order carries no meaning), and `components`; every shape key
-needs a set-wide component (`key` plus `text` or a manifest-relative `path`). A
-component may additionally specify `modelConfig` to override that key in a named
-profile. Create materializes each named profile with its complete base-plus-
-override component map. The default starts on the seed profile version. A profile with a
-production version resolves to that component map; a profile without one resolves to the
-default.
+The manifest contains `name`, optional unversioned `description`, the ordered
+component-key `shape`, and `components`; every shape key needs a set-wide
+component (`key` plus `text` or a manifest-relative `path`). A component may
+additionally specify `modelConfig` to override that key in a named profile.
+Create materializes each named profile with its complete base-plus-override
+component map. The default starts on the seed profile version. A profile with a
+production version resolves to that component map; a profile without one
+resolves to the default. Sets accept either their stable slug or exact display
+name. Archiving changes list visibility only, so archived sets still resolve
+and sync; use `--status archived` or `--status all` to find them before
+restoring.
 
 Shape changes create unpromoted profile heads but leave the default and
 production pointers in place. The instruction set does not resolve for affected
 model configs until those pointers move to their new shape-change versions; use
 the follow-up commands printed by the text CLI.
 
-Before a human moves a default, `default show` lists the model configs whose
+Before moving a default, `default show` lists the model configs whose
 resolution would change. A move targets a version by model-config identity and
 version number, and the database rejects an unsealed or non-commit-anchored
 component map. Shape changes create a new `shape_change` version for every profile;
 they do not repoint the default or any production label.
 
-Sync an offline runner directory with `orizu instruction-sets sync planner
---out ./instructions --project core/evals`. The layout is `manifest.json`,
+Sync an offline runner directory with `orizu instructions sync planner
+--out ./instructions --project core/evals`. The layout root is the stable set
+slug (`./instructions/planner/`), containing `manifest.json`,
 `default/<key>.md`, and `profiles/<identity-slug>/<key>.md`; loaders are
-`loadInstructionSet(dir, name, modelConfigIdentity)` in TypeScript and
-`load_instruction_set(dir, name, model_config_identity)` in Python. A
+`loadInstructionSet(dir, setReference, modelConfigIdentity)` in TypeScript and
+`load_instruction_set(dir, set_reference, model_config_identity)` in Python.
+Prefer the stable slug; exact manifest names remain accepted for compatibility. A
 Git-pinned component is recorded in the manifest but is intentionally not
 downloaded; either loader raises `instruction_set_component_unavailable`. A
 missing or unreadable local component file is distinct:
 `instruction_set_component_unreadable`.
 
-Use `profiles new` to seed an additional model-config profile from the default;
-hosted agents may do this because it does not move production. Use `profiles
+The sync manifest carries immutable `projectId` and `instructionSetId`; modern
+sync replacement requires both identities as well as the slug to match.
+Identity-less pre-slug trees are never auto-migrated: sync preserves them and
+returns `instruction_set_sync_legacy_identity_required`, requiring a verified
+clean output root or an explicit operator move.
+
+Use `profiles new` to seed an additional model-config profile from the default.
+Use `profiles
 promote` to move only that profile's production label; use `profiles rollback
 --to <n>` to create a new rollback version from the target version's component
-component map **and settings version** before moving it. Promotion and rollback are
-human-only because they move production labels.
+map **and settings version** before moving it. Follow the Authority map for
+promotion execution.
 
 For a single-component instruction set that wraps an existing prompt, only a
 promotion or rollback of the set's default profile also moves that prompt's
@@ -96,7 +112,7 @@ label` when a profile command performed this mirror.
 Execution/privacy defaults:
 
 - Runner subprocesses receive the input/output file-contract paths plus a small allowlist of provider/runtime environment variables. Orizu API tokens are not passed into runner processes. When an execution carries an instruction set, `ORIZU_INSTRUCTION_SET_DIR` is set explicitly to a fresh per-row synced layout; it is absent for legacy executions and is never inherited from the shell.
-- `orizu optimizations run-gepa` redacts dataset row payloads and reflection text in logged events by default. Use `--log-row-snapshots` only when the customer explicitly wants raw row and prompt text in the optimization event stream.
+- `orizu optimizations run-gepa` redacts dataset row payloads and reflection text in logged events by default. Use `--log-row-snapshots` only when the customer explicitly wants raw row and component text in the optimization event stream.
 - `run-gepa` still writes complete local traces under `logs/<optimization_run_id>` by default. Treat those logs as sensitive: they include row inputs, model outputs, scores, feedback, scorer responses, reflection prompts, reflection responses, and candidate text.
 - Runner artifacts, runner output, score result uploads, and optimization event payloads are size-capped. If a run needs larger observability payloads, store the large artifact separately and log a pointer.
 
@@ -116,7 +132,7 @@ Required file: `manifest.json`.
 }
 ```
 
-For `runners exec`, the command must read input JSON from `ORIZU_RUNNER_INPUT_PATH` and write output JSON to `ORIZU_RUNNER_OUTPUT_PATH`. When present, `ORIZU_INSTRUCTION_SET_DIR` contains the same layout written by `instruction-sets sync`; use `loadInstructionSet`/`load_instruction_set` to read materialized component text. Pinned components are represented in the manifest and are intentionally not materialized as `.md` files.
+For `runners exec`, the command must read input JSON from `ORIZU_RUNNER_INPUT_PATH` and write output JSON to `ORIZU_RUNNER_OUTPUT_PATH`. When present, `ORIZU_INSTRUCTION_SET_DIR` contains the same layout written by `instructions sync`; use `loadInstructionSet`/`load_instruction_set` to read materialized component text. Pinned components are represented in the manifest and are intentionally not materialized as `.md` files.
 
 Input shape:
 
@@ -237,36 +253,15 @@ seed before iterating. If the seed scores the worst possible value on every
 validation row (0.0 for higher-is-better, 1.0 for lower-is-better), errors on
 every row, or returns nothing parseable, the run fails loudly with a
 contract-mismatch diagnosis instead of silently burning budget on zeroed
-candidates. A uniformly-worst seed is almost always a harness bug, not a bad
-prompt; override with `--allow-degenerate-seed` only when the seed genuinely
+candidates. A uniformly-worst seed is almost always a harness bug, not bad
+component values; override with `--allow-degenerate-seed` only when the seed genuinely
 deserves the worst score everywhere.
 
-### Prompt Or Judge Directory
+### Judge Directory
 
 Required files: `orizu.prompt.json` plus the body file referenced by `body_file`.
 
-Generator prompt:
-
-```json
-{
-  "name": "hip-note-generator",
-  "role": "production_inference",
-  "description": "Generates a HIP note label.",
-  "body_file": "prompt.md",
-  "body_kind": "text",
-  "version_label": "v1",
-  "provider_settings": {
-    "model": "claude-sonnet-4-6",
-    "temperature": 0,
-    "max_tokens": 4096
-  },
-  "provenance": {
-    "kind": "coding-agent-edit"
-  }
-}
-```
-
-Judge prompt:
+Judge artifact:
 
 ```json
 {
@@ -391,27 +386,19 @@ eval "$(orizu --local env --project <team>/<project>)"
 ### Dataset Versions And Splits
 
 ```bash
-orizu --local datasets versions create <dataset-id-or-name> \
+orizu --local datasets upload \
+  --file ./dataset.jsonl \
   --project <team>/<project> \
-  --label v1 \
+  --name "<dataset-name>" \
+  --readme-file ./dataset-readme.md \
   --json
 ```
 
-Returns `dataset_version_id`.
-
-Create ratio-based splits:
-
-```bash
-orizu --local datasets splits create <dataset-version-id> \
-  --name default \
-  --seed 42 \
-  --train 0.6 \
-  --validation 0.4 \
-  --test 0 \
-  --json
-```
+Upload creates the initial immutable `v1` snapshot. Capture its returned
+`dataset_version_id`; do not immediately create a colliding `v1` version.
 
-Create predefined, Hugging Face-style splits:
+Review and commit a predefined split file with explicit train, validation, and
+reserved final-held-out membership:
 
 ```json
 {
@@ -421,13 +408,13 @@ Create predefined, Hugging Face-style splits:
   "partitions": [
     { "name": "train", "row_ids": ["row-1", "row-2"] },
     { "name": "validation", "row_ids": ["row-3"] },
-    { "name": "test", "row_ids": [] }
+    { "name": "final-held-out", "row_ids": ["row-4"] }
   ]
 }
 ```
 
 ```bash
-orizu --local datasets splits create <dataset-version-id> \
+orizu --local datasets splits create <upload-returned-dataset-version-id> \
   --from-file ./split.json \
   --json
 ```
@@ -440,12 +427,13 @@ Returns `split_set_id`.
 orizu --local runners push ./runner \
   --project <team>/<project> \
   --name hip-note-judge-runner \
-  --label default \
   --json
 ```
 
 Returns `runner_version_id`.
 
+The agent push is unlabeled. No standalone runner-label command exists, so never label by repeating a mutable working directory. If the human accepts the exact version as default, the human curator materializes it with `orizu --local runners pull hip-note-judge-runner --project <team>/<project> --version <reviewed-runner-version-id> --out ./runner-default-handoff`, does not alter that fresh directory, then runs `orizu --local runners push ./runner-default-handoff --project <team>/<project> --name hip-note-judge-runner --label default --json`. Pull verifies the content-addressed archive, and deterministic push excludes the pull sidecar, so this resolves the reviewed version before moving the pointer.
+
 Execute against a dataset split:
 
 ```bash
@@ -461,11 +449,15 @@ orizu --local runners exec \
 
 Omit `--runner-dir` to download and materialize the pinned runner version from Orizu. `--out` may end in `.jsonl` or `.jsonl.gz`.
 
-### Prompts And Judges
+### Instructions And Judges
+
+Prepare the complete instruction-set manifest and follow the Authority map for
+the push; the judge remains a git-canonical artifact.
 
 ```bash
-orizu --local prompts push ./prompt \
+orizu --local instructions push ./orizu.instruction-set.json \
   --project <team>/<project> \
+  --set <slug-or-exact-name> \
   --runner-version <runner-version-id> \
   --json
 
@@ -475,22 +467,27 @@ orizu --local judges push ./judge \
   --json
 ```
 
-Both commands return `prompt_version_id`.
+Instruction push returns the updated set and profile versions. Judge push
+returns `prompt_version_id` for the judge artifact used by scorer bindings.
 
 List:
 
 ```bash
-orizu --local prompts list --project <team>/<project>
-orizu --local prompts list --project <team>/<project> --status archived
-orizu --local prompts list --project <team>/<project> --status all
+orizu --local instructions list --project <team>/<project>
+orizu --local instructions list --project <team>/<project> --status archived
+orizu --local instructions list --project <team>/<project> --status all
 orizu --local judges list --project <team>/<project>
 ```
 
-Prompt and judge lists show active artifacts by default. Use `--status archived`
-or `--status all` when you need archived artifacts.
+Instruction and judge lists show active artifacts by default. Use `--status
+archived` or `--status all` when you need archived artifacts. Existing prompts
+appear in the instruction list as one-component sets; see
+`instructions-after-prompts.md` for ownership output, deliberate standalone
+mutation refusals, and manual consolidation.
 
-Prompt and judge list tables include `ID`, `NAME`, `ROLE`, `STATUS`, `TOKENS`,
-`LINES`, `CHARS`, and `WORDS`, measured from the latest sealed version. `—`
+Compatibility prompt and judge list tables include `ID`, `NAME`, `ROLE`,
+`STATUS`, `TOKENS`, `LINES`, `CHARS`, and `WORDS`, measured from the latest
+sealed version. `—`
 means the canonical body could not be measured; zero remains `0`. The `~`
 prefix on token counts means approximate: Orizu uses one fixed, model-agnostic
 `gpt-tokenizer` encoding rather than claiming an exact count for every model.
@@ -504,13 +501,17 @@ first 500 sorted summaries are enriched per request, and canonical-body
 resolution has a 15-second server budget. A summary skipped by either bound
 carries null stats and `measurement_cap_exceeded`.
 
-Archive or restore a prompt:
+Archive or restore an instruction set by stable slug or exact name, using the
+executor selected by the Authority map:
 
 ```bash
-orizu --local prompts archive <prompt-id-or-name> --project <team>/<project>
-orizu --local prompts restore <prompt-id-or-name> --project <team>/<project>
+orizu --local instructions archive <slug-or-exact-name> --project <team>/<project>
+orizu --local instructions restore <slug-or-exact-name> --project <team>/<project>
 ```
 
+Archive and restore affect visibility only. Archived sets still resolve and
+sync, and can be inspected with `instructions show --status archived|all`.
+
 List prompt comment threads for the latest version, or a specific label/version:
 
 ```bash
@@ -520,14 +521,19 @@ orizu --local comments list --prompt <prompt-id-or-name> \
   [--json]
 ```
 
-Human output shows the thread count, open/resolved counts, selected prompt text or source line, each top-level comment body, and replies. Use `--json` when an agent or script needs structured `summary` and `comments` data. Check unresolved comments before drafting or pushing the next prompt version.
+Human output shows the thread count, open/resolved counts, selected component
+text or source line, each top-level comment body, and replies. Use `--json` when
+an agent or script needs structured `summary` and `comments` data. Check
+unresolved comments before drafting or pushing the next instruction version.
 
-Move a mutable label:
+After the promotion decision, move a profile's production pointer
+through the Authority map:
 
 ```bash
-orizu --local prompts labels set hip-note-judge production \
+orizu --local instructions profiles promote hip-note-judge \
   --project <team>/<project> \
-  --version <prompt-version-id> \
+  --model-config <identity> \
+  --version <n> \
   --json
 ```
 
@@ -542,7 +548,6 @@ orizu --local scorers register \
   --manifest ./scorer.manifest.json \
   --prompt-version <judge-prompt-version-id> \
   --runner-version <judge-runner-version-id> \
-  --label production \
   --json
 ```
 
@@ -553,12 +558,10 @@ Inspect scorers:
 ```bash
 orizu --local scorers list --project <team>/<project>
 orizu --local scorers detail <scorer-id-or-name> --project <team>/<project> --json
-orizu --local scorers labels set hip-note-judge-score production \
-  --project <team>/<project> \
-  --version <scorer-version-id> \
-  --json
 ```
 
+Production scorer labels are pointer moves. The agent prepares the scorer name, version id, and evidence. After human acceptance, follow the [Authority map](../SKILL.md#authority-map): a human curator runs `orizu --local scorers labels set hip-note-judge-score production --version <scorer-version-id> --project <team>/<project> --json`.
+
 Use scorer versions directly with the runner contract:
 
 ```bash
@@ -682,18 +685,25 @@ orizu --local scores submit ./candidate-scores.jsonl \
   --json
 ```
 
-Bind scorers to prompt UI surfaces:
+Bind the headline scorer to the instruction component that owns the evaluated
+text:
 
 ```bash
-orizu --local prompts scorers set-headline <prompt-id> \
+orizu --local instructions scorers set-headline <set> \
+  --key <component-key> \
   --project <team>/<project> \
   --scorer-version <scorer-version-id> \
   --dataset-version <dataset-version-id> \
   --split-set <split-set-id> \
   --split validation \
   --json
+```
+
+Add tracked scorers to the same set-and-component address:
 
-orizu --local prompts scorers add <prompt-id> \
+```bash
+orizu --local instructions scorers add <set> \
+  --key <component-key> \
   --project <team>/<project> \
   --scorer-version <scorer-version-id> \
   --dataset-version <dataset-version-id> \
@@ -702,6 +712,12 @@ orizu --local prompts scorers add <prompt-id> \
   --json
 ```
 
+The legacy `prompts scorers set-headline` and `prompts scorers add` spellings
+refuse before making a request. Their measured replacements are:
+
+- `Use: orizu instructions scorers set-headline <set> --key <component-key> --scorer-version <id> --project <team/project>`
+- `Use: orizu instructions scorers add <set> --key <component-key> --scorer-version <id> --project <team/project>`
+
 ### Runs
 
 Submit local runner output:
@@ -736,11 +752,10 @@ orizu --local runs submit ./generator-results.jsonl \
 orizu --local optimizers push ./optimizer \
   --project <team>/<project> \
   --name hip-gepa-optimizer \
-  --label gepa-v1 \
   --json
 ```
 
-Returns `optimizer_version_id`.
+Returns `optimizer_version_id`; the agent-created version is unlabeled. If a human curator accepts that exact version as `gepa-v1`, the human pulls it with `orizu --local optimizers pull hip-gepa-optimizer --project <team>/<project> --version <optimizer-version-id> --out ./optimizer-label-handoff`, leaves that fresh directory unchanged, then runs `orizu --local optimizers push ./optimizer-label-handoff --project <team>/<project> --name hip-gepa-optimizer --label gepa-v1 --json`.
 
 Start a local optimization run before the optimizer process begins:
 
@@ -772,7 +787,9 @@ For bundled text-candidate GEPA-style optimization, let the CLI manage start/eve
 orizu --local optimizations run-gepa \
   --project <team>/<project> \
   --optimizer-version-id <optimizer-version-id> \
-  --candidate-version-id <prompt-version-id> \
+  --instruction-set <slug-or-exact-name> \
+  --model-config <identity> \
+  --component-selector all \
   --runner-version-id <runner-version-id> \
   --candidate-runner-dir ./candidate-runner \
   --scorer-version-id <row-scorer-version-id> \
@@ -790,10 +807,21 @@ orizu --local optimizations run-gepa \
 
 Useful GEPA flags:
 
+- `--instruction-set <slug-or-exact-name> --model-config <identity>` selects a
+  resolving instruction-set profile. `--component-selector round-robin|all`
+  controls which components GEPA proposes changing; `all` lets it optimize the
+  complete component map. `--candidate-version-id` remains a compatibility
+  input for a single legacy prompt version and is mutually exclusive with the
+  instruction-set selector.
 - `--engine official|legacy` defaults to `official`, which runs the bundled official GEPA connector. Use `legacy` only as the frozen recovery hatch; it keeps the historical Python loop and does not support `--max-candidate-proposals` or the skilled proposer.
 - `--scorer-input-contract gepa|flat_row` selects the scorer-runner input shape. Use `flat_row` to reuse a judge runner written for `runners exec --scorer-version` without a hand-written adapter; add `--scorer-candidate-field <row-field>` when that judge reads the candidate output from a specific row field (e.g. `draft`). Passing a candidate field under the `gepa` contract is refused at launch, not silently ignored. See "Scorer-Runner Input Contracts" above.
 - `--allow-degenerate-seed` opts out of the launch-time refusal when the seed scores the worst possible value on every validation row. Leave it off by default — a uniformly-worst seed is almost always a scorer contract mismatch.
 - Budget controls are mutually exclusive: choose at most one of `--budget auto|light|medium|heavy`, `--max-metric-calls <n>`, `--max-full-evals <n>`, `--max-iterations <n>`, or `--max-candidate-proposals <n>`. With none provided, `run-gepa` defaults to `--budget auto`, the balanced medium preset. `--max-candidate-proposals` is available only with `--engine official`.
+- Hosted optimization (`--hosted`) is launched only by a human/PAT caller on
+  an enabled team. It accepts a named `--budget` preset only, does not require
+  candidate/scorer runner directories or local logs, and sends no local runner
+  bytes or provider credentials. Reuse `--launch-intent-id <uuid>` after a lost
+  response; use a new intent when the project or job specification changes.
 - `--minibatch-size <n>` defaults to 3.
 - `--num-threads auto|N` defaults to `auto`; auto caps row-evaluation concurrency from mini-batch size, validation-set size, 2x CPU count, memory estimate, file-descriptor limit, and a 64-thread default ceiling. Set `ORIZU_GEPA_AUTO_THREADS_MAX` or use `--num-threads <n>` only when the runner/provider capacity is known.
 - `--candidate-selection-strategy pareto|current_best|epsilon_greedy`; default is `pareto`. With `epsilon_greedy`, `--epsilon <n>` controls the random-selection probability (default `0.1`, clamped to `0`–`1`).
@@ -801,9 +829,9 @@ Useful GEPA flags:
 - `--reflection-model <provider/model>`, `--reflection-temperature <n>`, `--reflection-prompt-template <text|@file>`.
 - `--reflection-max-tokens <n>` is explicit provider config, not a global default. It maps to Anthropic `max_tokens` and OpenAI `max_output_tokens`; Anthropic native Messages reflection requires it, while OpenAI can omit it unless the user wants a cap.
 - `--reflection-retry-attempts` and `--reflection-http-timeout-seconds` tune transient reflection-provider retries. Exhausted retryable failures log `reflection_failed`, count against candidate-proposal budget, and continue with the next iteration.
-- `--reflection-provider-settings <json|@file>` passes provider-native reflection settings separately from the prompt text. Anthropic example: `{"thinking":{"type":"adaptive","display":"omitted"},"output_config":{"effort":"medium"}}`. OpenAI example: `{"reasoning":{"effort":"medium","summary":"auto"}}`.
+- `--reflection-provider-settings <json|@file>` passes provider-native reflection settings separately from the component text. Anthropic example: `{"thinking":{"type":"adaptive"},"output_config":{"effort":"medium"}}`. OpenAI example: `{"reasoning":{"effort":"medium","summary":"auto"}}`.
 - `--disable-evaluation-cache` turns off candidate/row/scorer cache reuse.
-- `--auto-promote --promotion-label <label>` promotes the best candidate at the end.
+- `--auto-promote --promotion-label <label>` can move a label to the best candidate at the end. Omit both flags: run without auto-promotion, write the report, obtain the human promotion decision, then route the manual promotion command through the Authority map.
 - `--log-row-snapshots` includes raw row and reflection text in events; leave off by default.
 - `--log-dir <dir>` controls the local log root; default is `logs`.
 - `--no-local-log` disables local trace files. Use this only when the environment must not persist raw rows or reflection context.
@@ -812,6 +840,10 @@ Useful GEPA flags:
 
 `--candidate-proposer skilled-proposer` selects the skilled proposer; omission keeps the default official proposer. The flag is official-engine-only and accepts that one value. A missing value is refused before launch as `--candidate-proposer requires a value that does not start with --`; another value is refused as `--candidate-proposer must be skilled-proposer`; selecting it with `--engine legacy` is refused with `--candidate-proposer is supported by the official GEPA engine only`.
 
+`--candidate-proposer-config <@file|path>` is optional and requires that selection on the official engine. Its strict schema-v1 object requires `schemaVersion: 1` and `skills: []`; each ordered skill is exactly either `{ "path": "..." }` (with optional `name`/`description` overrides) or `{ "name": "...", "description": "...", "inline": "..." }`. Optional fields are `additionalInstructionsFile`, `baseInstructionsFile`, positive-integer-or-null `maxWords`, `maxTokens`, and `maxExamples`, plus `onError: "keep"|"raise"`. Paths are config-file-relative; directories read only `SKILL.md`. Missing, unreadable, empty, malformed, ambiguous, duplicate-name, and unknown-field inputs fail before launch. `baseInstructionsFile` is advanced use: it replaces upstream's built-in anti-overfitting meta-prompt.
+
+`--reflection-prompt-template` is incompatible whenever skilled-proposer is selected, with or without a proposer config; it configures the ordinary GEPA reflection path and would otherwise be silently ignored. The three token controls have different scopes: `--reflection-max-tokens` caps one provider response, config `maxTokens` caps a proposed instruction, and `--proposal-max-tokens` caps aggregate proposal-provider usage.
+
 `--proposal-max-calls <positive-integer>` and `--proposal-max-tokens <positive-integer>` default to unset and are valid only with the skilled proposer. A missing operand names that flag; using either ceiling without the selection produces `--proposal-max-calls and --proposal-max-tokens require --candidate-proposer skilled-proposer`; the legacy-engine error names the individual flag. Integer and positive-value validation happens in the connector after launch and names `ORIZU_PROPOSAL_MAX_CALLS` or `ORIZU_PROPOSAL_MAX_TOKENS`.
 
 The call ceiling counts each transport-bearing proposer bridge call after its success or failure is recorded; provider retries inside one bridge call remain one counted call. The token ceiling uses accumulated provider-derived `total_tokens`, including recorded usage from unsuccessful completions. Both ceilings stop new proposal work at the next safe boundary, so an in-flight call can meet or pass a ceiling. They govern only the skilled proposer and remain independent of overall GEPA controls such as `--max-metric-calls`; set at least one proposal ceiling and one overall GEPA ceiling, then start the run only when both limits match the intended experiment.
@@ -854,10 +886,11 @@ orizu --local optimizations export <optimization-run-id> \
 
 Use export when the local log is unavailable, the run happened on another machine, or a coding agent needs a portable single JSON artifact. The export fetches all optimization events, derives seed vs best, Pareto frontier, score-over-time, candidates, iterations, minibatch rows, and validation rows, and rehydrates row inputs from the dataset version artifact when possible. Server events may not contain row snapshots or reflection prompts unless the run used `--log-row-snapshots`; reflection responses are included for bundled `run-gepa` runs.
 
-Both diff-comment read routes (`/api/optimization-runs/<run-id>/diff-comments` and
-`/api/prompts/<prompt-id>/diff-comments`) return `componentKey` for tuple
-comments. Preserve it on writes and use it in grouping keys: equal line ranges
-from different instruction-set components are distinct comments.
+Both diff-comment read routes (`/api/optimization-runs/<run-id>/diff-comments`
+and `/api/prompts/<prompt-id>/diff-comments`) return `componentKey` for
+multi-component comments. Preserve it on writes and use it in grouping keys:
+equal line ranges from different instruction-set components are distinct
+comments.
 
 The v1 export keeps the run row's `best_candidate_id` in
 `summary.bestCandidateId` when event derivation rejects that identifier as an
@@ -866,20 +899,46 @@ identifier. If neither source names a best candidate, the field is `null`.
 
 Lifecycle controls:
 
+Agent-run pause and resume controls:
+
 ```bash
 orizu --local optimizations pause <optimization-run-id> --reason "inspect candidate"
 orizu --local optimizations resume <optimization-run-id>
-orizu --local optimizations finish <optimization-run-id> \
-  --best-score 0.82 \
-  --best-candidate candidate-7 \
-  --result-prompt-version <prompt-version-id> \
-  --report-file ./reports/<optimization-run-id>.md
+```
+
+**Multi-component instruction-set run.** The agent materializes the candidate
+without a label, then finishes without putting the returned profile version ID
+in the prompt-only result field:
+
+```bash
+orizu --local optimizations promote <optimization-run-id> --candidate <candidate-id>
+orizu --local optimizations finish <optimization-run-id> --best-candidate <candidate-id> --report-file ./reports/<optimization-run-id>.md
+```
+
+**Plain-prompt run.** A human curator runs the promotion as `orizu --local optimizations promote <optimization-run-id> --candidate <candidate-id> --label production`; this is the one allowed live promotion.
+
+After the human returns `promptVersionId`, the agent records it on finish:
+
+```bash
+orizu --local optimizations finish <optimization-run-id> --best-candidate <candidate-id> --result-prompt-version <prompt-version-id> --report-file ./reports/<optimization-run-id>.md
+```
+
+**Set-of-one instruction-set run.** The agent must never call `optimizations promote`; follow `optimization-reports.md`'s provenance
+stop/doctrine and finish without a result:
+
+```bash
+orizu --local optimizations finish <optimization-run-id> --best-candidate <candidate-id> --report-file ./reports/<optimization-run-id>.md
+```
+
+Agent-run failure and cancellation controls:
+
+```bash
 orizu --local optimizations fail <optimization-run-id> --reason "provider outage" --report-file ./reports/<optimization-run-id>.md
 orizu --local optimizations cancel <optimization-run-id> --reason "user stopped" --report "## Cancelled\n\nStopped after manual inspection."
 ```
 
 `pause` and `cancel` store `metadata.reason`. `fail` stores `metadata.failure_reason`.
-`finish` marks the run `succeeded`; use it after accepted candidates have been promoted and the final prompt version is known.
+`finish` marks the run `succeeded` and attaches its report; it does not authorize promotion. The three subject branches above are normative; see `optimization-reports.md` for seed-selected and no-valid-candidate branches. Finish the report first, then obtain the human decision before materialization or a serving-pointer move.
 Use `--report-file <path>` or `--report <markdown|@file>` on `finish`, `fail`, or `cancel` to attach the markdown report shown in the optimization detail Report tab. Prefer generating this from the local GEPA logs (`result.json`, `evaluations.jsonl`, `reflections.jsonl`, and `events.jsonl`) after the run ends. Report structure and interpretation rules: `optimization-reports.md`.
 
 ## Optimization Event Logging
@@ -966,8 +1025,7 @@ curl -sS -X POST "$ORIZU_API_URL/api/cli/optimization-runs/$ORIZU_RUN_ID/promote
     "temperature": 0,
     "max_tokens": 4096
   },
-  "runnerVersionId": "runner-version-uuid",
-  "label": "production"
+  "runnerVersionId": "runner-version-uuid"
 }
 ```
 
@@ -981,16 +1039,26 @@ Response:
 
 ## End-to-End Flow
 
+Use a JSON array for `dataset.json` in this piped form. JSONL uploads use the
+chunked uploader, which writes progress lines to stdout before its final JSON
+document even with `--json`, so piping that stdout directly to `jq` is invalid.
+
 ```bash
 eval "$(orizu --local env --project hip/judge-optimization)"
 
-DATASET_VERSION_ID="$(orizu --local datasets versions create hip-note-judge-labels --project hip/judge-optimization --label v1 --json | jq -r .dataset_version_id)"
-SPLIT_SET_ID="$(orizu --local datasets splits create "$DATASET_VERSION_ID" --name default --seed 42 --train 0.6 --validation 0.4 --test 0 --json | jq -r .split_set_id)"
+DATASET_VERSION_ID="$(orizu --local datasets upload --file ./dataset.json --project hip/judge-optimization --name hip-note-judge-labels --readme-file ./dataset-readme.md --json | jq -r .dataset_version_id)"
+SPLIT_SET_ID="$(orizu --local datasets splits create "$DATASET_VERSION_ID" --from-file ./split.json --json | jq -r .split_set_id)"
 
-RUNNER_VERSION_ID="$(orizu --local runners push ./runner --project hip/judge-optimization --name hip-note-judge-runner --label default --json | jq -r .runner_version_id)"
+RUNNER_VERSION_ID="$(orizu --local runners push ./runner --project hip/judge-optimization --name hip-note-judge-runner --json | jq -r .runner_version_id)"
 JUDGE_VERSION_ID="$(orizu --local judges push ./judge --project hip/judge-optimization --runner-version "$RUNNER_VERSION_ID" --json | jq -r .prompt_version_id)"
-SCORER_VERSION_ID="$(orizu --local scorers register --project hip/judge-optimization --name hip-note-judge-score --manifest ./scorer.manifest.json --prompt-version "$JUDGE_VERSION_ID" --runner-version "$RUNNER_VERSION_ID" --label production --json | jq -r .scorer_version_id)"
-OPTIMIZER_VERSION_ID="$(orizu --local optimizers push ./optimizer --project hip/judge-optimization --name hip-gepa-optimizer --label gepa-v1 --json | jq -r .optimizer_version_id)"
+SCORER_VERSION_ID="$(orizu --local scorers register --project hip/judge-optimization --name hip-note-judge-score --manifest ./scorer.manifest.json --prompt-version "$JUDGE_VERSION_ID" --runner-version "$RUNNER_VERSION_ID" --json | jq -r .scorer_version_id)"
+```
+
+Human curator hand-off through the [Authority map](../SKILL.md#authority-map) (do not run as the agent): no standalone runner-label command exists, so the human first runs `orizu --local runners pull hip-note-judge-runner --project hip/judge-optimization --version "$RUNNER_VERSION_ID" --out ./runner-default-handoff`, leaves that fresh exact-version directory unchanged, then runs `orizu --local runners push ./runner-default-handoff --project hip/judge-optimization --name hip-note-judge-runner --label default --json`. The human curator then runs `orizu --local scorers labels set hip-note-judge-score production --version "$SCORER_VERSION_ID" --project hip/judge-optimization --json`.
+The agent continues with an unlabeled optimizer version:
+
+```bash
+OPTIMIZER_VERSION_ID="$(orizu --local optimizers push ./optimizer --project hip/judge-optimization --name hip-gepa-optimizer --json | jq -r .optimizer_version_id)"
 OPTIMIZATION_RUN_ID="$(orizu --local optimizations start --project hip/judge-optimization --optimizer-version "$OPTIMIZER_VERSION_ID" --prompt-version "$JUDGE_VERSION_ID" --selection-scorer "$SCORER_VERSION_ID" --reflection-scorer "$SCORER_VERSION_ID" --dataset-version "$DATASET_VERSION_ID" --split-set "$SPLIT_SET_ID" --json | jq -r .optimization_run_id)"
 export ORIZU_RUN_ID="$OPTIMIZATION_RUN_ID"
 
@@ -1019,11 +1087,11 @@ orizu --local scores submit ./judge-results.jsonl \
   --split-set "$SPLIT_SET_ID" \
   --split validation
 
-# After the local optimizer has logged events and promoted its accepted candidate:
+# After the local optimizer has logged events: finish and attach the report, obtain human acceptance, then hand the one-shot promotion to a human curator.
 orizu --local optimizations finish "$OPTIMIZATION_RUN_ID" \
   --best-score 0.82 \
   --best-candidate candidate-7 \
-  --result-prompt-version "$JUDGE_VERSION_ID"
+  --report-file "./reports/$OPTIMIZATION_RUN_ID.md"
 ```
 
 ## Notes And Limits