orizu 0.3.7 → 0.4.1

package/vendor/skills/orizu-cli/references/cli-reference.md

@@ -12,8 +12,9 @@
 1. Verify auth first: `orizu whoami`.
 2. Prefer explicit flags over prompts.
 3. Use interactive fallback only in TTY sessions.
-4. Validate command output before proceeding.
-5. On failure, fix flags/identifiers and rerun.
+4. Prefer `--json` for machine-readable output — every command supports it (prefix `orizu --json <cmd>` or trailing flag). Long-running commands emit the JSON summary as the final stdout line.
+5. Validate command output before proceeding.
+6. On failure, fix flags/identifiers and rerun.
 
 ## Command Matrix
 
@@ -33,6 +34,25 @@ Behavior:
 - PATs can also be revoked from the Personal Tokens page in Orizu.
 - PAT authorization follows the owning user's current team/project roles, so demotion or removal takes effect without rotating the token.
 
+### Agent Setup
+
+```bash
+orizu capabilities --json
+orizu skills path [--skill-md] [--json]
+orizu skills status [--json]
+orizu skills update [--dry-run] [--json]
+orizu install-skill [--agent <claude|codex>]... [--scope global|project] [--mode auto|link|copy] [--yes] [--dry-run] [--json]
+orizu setup [--agent <claude|codex>]... [--skip-login] [--no-install] [--workspace|--no-workspace] [--no-handoff] [--yes] [--dry-run] [--no-input] [--json]
+orizu setup prompt [--json]
+```
+
+Behavior:
+- `capabilities --json` returns the full machine-readable command manifest, including `globalOptions`.
+- `skills path --json` returns where this skill's source lives (`root`, `skillMd`, `source`, `cliVersion`, `skillHash`) so you can read it without installing, and verify an installed copy matches the CLI.
+- `skills status` reports each install target as missing/current/stale/broken-link; `skills update` refreshes stale copies and repairs broken symlinks.
+- `install-skill` selects targets by agent name; `--scope global` (default) installs user-level, `--scope project` into the repo. Project-scope installs always copy; global installs symlink when the CLI path is stable. Advanced target IDs remain available via `--target`.
+- `orizu setup` is the guided onboarding flow (login → agent integration → `.orizu/` workspace → handoff prompt). `orizu setup prompt` prints the repo-adoption prompt for handing to a coding agent.
+
 ### Teams
 
 ```bash
@@ -166,23 +186,28 @@ orizu tasks create \
 Behavior:
 - task creation creates a draft by default and returns a task URL to test manually before assigning
 - use `--publish --assignees <userIdOrEmail1,userIdOrEmail2>` only when you intentionally want to create and ship immediately
+- use `--assignment-file <path>` instead of `--assignees` when specific rows should go to specific labellers
 - after manually approving a draft, run `orizu tasks publish --task <taskId> --assignees <userId1,userId2>`
+- or run `orizu tasks publish --task <taskId> --assignment-file <path>` to publish the exact row map
 - task creation resolves and stores the app's pinned current `version_id` at create time
 - downstream consumers (exports, judges, optimization) should trust the task's pinned `version_id`, not the app's current pointer
 - dataset compatibility is validated against that pinned app version before the task is inserted
 - malformed JSON and mixed-type assignee arrays fail with deterministic `400` responses
 - assignment fanout enforces unique `(assignee, row)` pairs; `--labels-per-item` cannot exceed the number of unique assignees, and the backend shortfalls instead of duplicating
+- explicit assignment manifests are JSONL with `rowId` plus `assignee` or `assignees`; row IDs are canonical dataset row `id` values, assignees may be emails or user IDs, and V1 publish requires whole-dataset uniform coverage
 
 Publish:
 
 ```bash
 orizu tasks publish --task <taskId> --assignees <userId1,userId2>
+orizu tasks publish --task <taskId> --assignment-file ./assignments.jsonl
 ```
 
 Assign:
 
 ```bash
 orizu tasks assign --task <taskId> --assignees <userId1,userId2>
+orizu tasks assign --task <taskId> --assignment-file ./assignments.jsonl --replace-existing
 ```
 
 Status:
@@ -232,13 +257,14 @@ For prompts, judges, runners, run submission, optimizer artifacts, live event lo
 Optimization trace commands:
 
 ```bash
-orizu optimizations run-gepa ... [--num-threads auto|N] [--log-dir logs] [--no-local-log]
+orizu optimizations run-gepa ... [--num-threads auto|N] [--reflection-retry-attempts 3] [--reflection-http-timeout-seconds 180] [--log-dir logs] [--no-local-log]
 orizu optimizations export <optimization-run-id> --out ./optimization.json
 orizu optimizations export <optimization-run-id> --json
 ```
 
 Behavior:
-- `run-gepa` defaults `--num-threads` to `auto`, resolving a conservative row-evaluation parallelism cap from mini-batch size, validation-set size, CPU count, memory estimate, file-descriptor limit, and an 8-thread hard cap.
+- `run-gepa` defaults `--num-threads` to `auto`, resolving a row-evaluation parallelism cap 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.
+- `run-gepa` retries transient reflection-provider failures by default. If retries are exhausted, it logs `reflection_failed`, counts that reflection proposal against budget, and continues with the next iteration.
 - `run-gepa` writes a complete local trace under `logs/<optimization_run_id>` by default.
 - The local trace is the best artifact for coding-agent analysis because it includes full rows, outputs, scores, feedback, scorer responses, reflection prompts, reflection responses, candidate text, and `result.json`.
 - `optimizations export` writes a portable JSON artifact from server data when the local log is unavailable or the run happened elsewhere.
@@ -280,6 +306,8 @@ orizu tasks create \
 
 # Open the returned task URL and test the draft manually before assigning.
 orizu tasks publish --task <taskId> --assignees <userId1,userId2>
+# Or publish a deterministic row map:
+orizu tasks publish --task <taskId> --assignment-file ./assignments.jsonl
 
 orizu tasks status --task <taskId>
 orizu tasks export --task <taskId> --format csv --out ./support-round1.csv
@@ -300,7 +328,8 @@ Use these shortcuts only in TTY environments where prompts can run.
 
 - `tasks create` creates a draft by default, does not require `--assignees`, and pins the app's current version when the task is created.
 - `tasks create --publish --assignees <...>` intentionally creates and ships immediately.
-- `tasks assign` and `tasks publish` expect user IDs, not emails.
+- `tasks create|publish|assign --assignment-file <path>` is mutually exclusive with `--assignees` and accepts emails or user IDs in the JSONL manifest.
+- `tasks assign --assignees` and `tasks publish --assignees` expect user IDs, not emails.
 - Assignment queue reads are assignee-self-only; use task status/export as the operator summary path.
 - Assignment completion payloads are validated against the pinned app-version `output_json_schema`.
 - `datasets delete-rows` requires `--row-ids`.

package/vendor/skills/orizu-cli/references/optimization-reports.md

@@ -130,9 +130,9 @@ Set an explicit expectation before the run: for example, "if best kappa does not
 
 ### Budget Versus Iteration Cap
 
-Default budget presets are DSPy-style metric-call budgets. `light`, `medium`, and `heavy` map to DSPy's `auto="light"`, `auto="medium"`, and `auto="heavy"` scales; `auto` is treated as the balanced `medium` preset. The final metric-call limit scales with validation-set size, rather than using fixed tiny constants. `--max-metric-calls` overrides this directly, while `--max-full-evals` is converted to a metric-call budget over `train + validation` rows.
+Default budget presets are DSPy-style metric-call budgets. `light`, `medium`, and `heavy` map to DSPy's `auto="light"`, `auto="medium"`, and `auto="heavy"` scales; `auto` is treated as the balanced `medium` preset and is the default when no budget control is provided. The final metric-call limit scales with validation-set size, rather than using fixed tiny constants. `--budget`, `--max-metric-calls`, `--max-full-evals`, and `--max-iterations` are mutually exclusive CLI budget controls; choose only one.
 
-Budget is checked only between iterations. Once an iteration starts, `run-gepa` completes the parent minibatch, child minibatch, and full validation eval for an accepted child even if that overshoots the nominal budget. If a run ends as `budget_exhausted`, it pauses and does not auto-promote. If auto-promotion matters, either increase budget to fit the iteration target or lower `--max-iterations` to fit the budget.
+Metric-call and full-eval budgets are checked only between iterations. Once an iteration starts, `run-gepa` completes the parent minibatch, child minibatch, and full validation eval for an accepted child even if that overshoots the nominal budget. If a run ends as `budget_exhausted`, it pauses and does not auto-promote. If auto-promotion matters, choose a single budget control large enough to cover the intended search.
 
 ### Reflection Signal Quality
 

package/vendor/skills/orizu-cli/references/optimization-with-gepa.md

@@ -62,6 +62,7 @@ Reflection output contract:
 - The default reflection prompt asks for only the complete updated prompt body. Do not ask the model to wrap the candidate in markdown fences or tags; real prompts often contain those characters.
 - Put provider-native reasoning controls in `--reflection-provider-settings <json|@file>`, not in the prompt body. For OpenAI reasoning models, use a shape such as `{"reasoning":{"effort":"medium","summary":"auto"}}`. For Anthropic Claude models with thinking controls, use a shape such as `{"thinking":{"type":"adaptive","display":"omitted"},"output_config":{"effort":"medium"}}`.
 - Reflection max-token limits are explicit. `--reflection-max-tokens <n>` maps to Anthropic `max_tokens` and OpenAI `max_output_tokens`; Anthropic native Messages reflection requires it, while OpenAI may omit it when no cap is desired.
+- Reflection HTTP calls retry transient failures by default (`--reflection-retry-attempts 3`, `--reflection-http-timeout-seconds 180`). Exhausted retryable failures emit `reflection_failed`, consume one candidate-proposal budget slot, and move to the next iteration instead of killing the run.
 
 Full command syntax and event contracts: `prompt-control-plane.md`.
 

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

@@ -332,9 +332,21 @@ 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 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.
+
+Archive or restore a prompt:
+
+```bash
+orizu --local prompts archive <prompt-id-or-name> --project <team>/<project>
+orizu --local prompts restore <prompt-id-or-name> --project <team>/<project>
+```
+
 List prompt comment threads for the latest version, or a specific label/version:
 
 ```bash
@@ -607,20 +619,19 @@ orizu --local optimizations run-gepa \
   --train-split train \
   --val-split validation \
   --log-dir ./logs \
-  --budget light \
-  --max-iterations 3 \
   --minibatch-size 3 \
   --num-threads auto
 ```
 
 Useful GEPA flags:
 
-- `--budget auto|light|medium|heavy`, `--max-metric-calls <n>`, `--max-full-evals <n>`.
+- Budget controls are mutually exclusive: choose at most one of `--budget auto|light|medium|heavy`, `--max-metric-calls <n>`, `--max-full-evals <n>`, or `--max-iterations <n>`. With none provided, `run-gepa` defaults to `--budget auto`, the balanced medium preset.
 - `--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, CPU count, memory estimate, file-descriptor limit, and an 8-thread hard cap.
+- `--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`.
 - `--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"}}`.
 - `--disable-evaluation-cache` turns off candidate/row/scorer cache reuse.
 - `--auto-promote --promotion-label <label>` promotes the best candidate at the end.
@@ -718,7 +729,8 @@ Rules:
 - `eventId` must be stable and unique within one optimization run.
 - `eventLayer` is `core`, `extension`, or `system`.
 - Generic core events: `run_started`, `iteration_started`, `candidate_proposed`, `candidate_scored`, `candidate_recommended`, `iteration_completed`, `run_completed`, `run_failed`.
-- GEPA extension events: `seed_val_set_started`, `seed_val_set_completed`, `parent_minibatch_started`, `parent_minibatch_completed`, `reflection_started`, `reflection_completed`, `child_candidate_created`, `child_minibatch_started`, `child_minibatch_completed`, `acceptance_decision_made`, `merge_started`, `merge_completed`.
+- GEPA extension events: `seed_val_set_started`, `seed_val_set_completed`, `parent_minibatch_started`, `parent_minibatch_completed`, `reflection_started`, `reflection_completed`, `child_candidate_created`, `child_minibatch_started`, `child_minibatch_completed`, `acceptance_decision_made`, `optimization_progress`, `merge_started`, `merge_completed`.
+- Emit `optimization_progress` after each completed iteration with `percent`, `metric_calls_used`, `metric_call_budget`, and `metric_calls_remaining`. Cap displayed `percent` at `100` and floor `metric_calls_remaining` at `0`; a started iteration may spend past the nominal metric-call budget before the optimizer pauses.
 - Do not send per-LM-call telemetry to this endpoint in Phase 0. Put aggregate call/token/cost stats in iteration or run payloads.
 
 Shell fallback: