orizu 0.5.19 → 0.5.21

package/vendor/orizu-gepa-python/src/orizu_gepa/runner.py

@@ -1,10 +1,12 @@
 from __future__ import annotations
 
 import json
+import hashlib
 import os
 import subprocess
 import tempfile
 import zipfile
+import re
 from pathlib import Path
 from typing import Any
 
@@ -38,7 +40,7 @@ ALLOWED_RUNNER_ENV_KEYS = {
 
 def read_manifest(runner_dir: str | Path) -> dict[str, Any]:
     path = Path(runner_dir) / "manifest.json"
-    return json.loads(path.read_text())
+    return json.loads(path.read_text(encoding="utf-8"))
 
 
 def _safe_extract_zip(zip_path: Path, destination: Path) -> None:
@@ -64,7 +66,7 @@ def _safe_extract_zip(zip_path: Path, destination: Path) -> None:
         archive.extractall(destination)
 
 
-def _runner_env(input_path: Path, output_path: Path) -> dict[str, str]:
+def _runner_env(input_path: Path, output_path: Path, instruction_set_dir: Path | None = None) -> dict[str, str]:
     env = {
         key: value
         for key, value in os.environ.items()
@@ -72,9 +74,156 @@ def _runner_env(input_path: Path, output_path: Path) -> dict[str, str]:
     }
     env["ORIZU_RUNNER_INPUT_PATH"] = str(input_path)
     env["ORIZU_RUNNER_OUTPUT_PATH"] = str(output_path)
+    env.pop("ORIZU_INSTRUCTION_SET_DIR", None)
+    if instruction_set_dir is not None:
+        env["ORIZU_INSTRUCTION_SET_DIR"] = str(instruction_set_dir)
     return env
 
 
+def _instruction_component(component: Any) -> tuple[str | None, dict[str, str] | None]:
+    if isinstance(component, str):
+        return component, None
+    if not isinstance(component, dict):
+        raise RuntimeError("instruction_set_unresolvable")
+    body = component.get("body")
+    if isinstance(body, str):
+        return body, None
+    repo_path = component.get("repoPath", component.get("repo_path"))
+    content_sha = component.get("contentSha", component.get("content_sha"))
+    commit_sha = component.get("commitSha", component.get("commit_sha"))
+    if all(isinstance(value, str) and value for value in (repo_path, content_sha, commit_sha)):
+        return None, {"repoPath": repo_path, "contentSha": content_sha, "commitSha": commit_sha}
+    raise RuntimeError("instruction_set_unresolvable")
+
+
+SAFE_SEGMENT = re.compile(r"^[A-Za-z0-9._-]+$")
+
+
+def _safe_segment(value: str) -> None:
+    if not SAFE_SEGMENT.fullmatch(value) or value in {".", ".."} or value.startswith("."):
+        raise RuntimeError("instruction_set_path_unsafe")
+
+
+def _slug(identity: str) -> str:
+    return re.sub(r"[^A-Za-z0-9._-]", "_", identity.replace("/", "__"))
+
+
+def _write_instruction_set_layout(root: Path, instruction_set: dict[str, Any]) -> None:
+    """Mirror the CLI syncToDisk manifest/layout for one exact tuple."""
+    name = instruction_set.get("name")
+    shape = instruction_set.get("shape")
+    model_config = instruction_set.get("model_config", instruction_set.get("modelConfig"))
+    if not isinstance(name, str) or not isinstance(shape, list) or not all(isinstance(key, str) for key in shape):
+        raise RuntimeError("instruction_set_unresolvable")
+    if not isinstance(model_config, dict) or not isinstance(model_config.get("identity"), str):
+        raise RuntimeError("instruction_set_unresolvable")
+    components = dict(instruction_set.get("components") or {})
+    components.update(instruction_set.get("pinned_components", instruction_set.get("pinnedComponents", {})) or {})
+    if any(key not in components for key in shape):
+        raise RuntimeError("instruction_set_tuple_incomplete")
+    if not isinstance(components, dict):
+        raise RuntimeError("instruction_set_unresolvable")
+    profile_version_id = instruction_set.get("profile_version_id", instruction_set.get("profileVersionId"))
+    version_number = instruction_set.get("version_number", instruction_set.get("versionNumber"))
+    if not isinstance(profile_version_id, str) or not isinstance(version_number, int):
+        raise RuntimeError("instruction_set_unresolvable")
+
+    _safe_segment(name)
+    for key in shape:
+        _safe_segment(key)
+    identity = model_config["identity"]
+    slug = _slug(identity)
+    _safe_segment(slug)
+    destination = root / name
+    destination.mkdir(parents=True, exist_ok=True)
+
+    def write_material(relative_root: str) -> dict[str, Any]:
+        files: dict[str, str] = {}
+        synced_content_sha256: dict[str, str] = {}
+        pinned_components: dict[str, dict[str, str]] = {}
+        for key in sorted(shape):
+            if key not in components:
+                raise RuntimeError("instruction_set_unresolvable")
+            body, pin = _instruction_component(components[key])
+            if body is not None:
+                relative = f"{relative_root}/{key}.md"
+                target = destination / relative
+                target.parent.mkdir(parents=True, exist_ok=True)
+                target.write_text(body, encoding="utf-8")
+                files[key] = relative
+                synced_content_sha256[key] = hashlib.sha256(body.encode("utf-8")).hexdigest()
+            elif pin is not None:
+                pinned_components[key] = pin
+        material: dict[str, Any] = {
+            "profileVersionId": profile_version_id,
+            "versionNumber": version_number,
+            "modelConfigIdentity": identity,
+            "resolvedFrom": "exact_profile_version",
+            "files": files,
+            "syncedContentSha256": synced_content_sha256,
+        }
+        if pinned_components:
+            material["pinnedComponents"] = pinned_components
+        return material
+
+    material = write_material("default")
+    profile = {
+        "modelConfigIdentity": identity,
+        "slug": slug,
+        "resolvedFrom": "exact_profile_version",
+        "production": write_material(f"profiles/{slug}"),
+    }
+    authoring_components = [
+        {
+            "key": key,
+            "path": relative,
+            "syncedContentSha256": material["syncedContentSha256"][key],
+        }
+        for key, relative in material["files"].items()
+    ]
+    authoring_components.extend(
+        {
+            "key": key,
+            "modelConfig": identity,
+            "path": relative,
+            "syncedContentSha256": profile["production"]["syncedContentSha256"][key],
+        }
+        for key, relative in profile["production"]["files"].items()
+    )
+    manifest = {
+        "manifestVersion": 1,
+        "name": name,
+        "shape": shape,
+        "components": authoring_components,
+        "default": material,
+        "profiles": [profile],
+    }
+    (destination / "manifest.json").write_text(json.dumps(manifest, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+
+
+def _runner_instruction_set_payload(instruction_set: dict[str, Any]) -> dict[str, Any]:
+    """The runner receives the tuple, while sync-only provenance stays on disk."""
+    components: dict[str, Any] = {}
+    pinned_components: dict[str, Any] = dict(instruction_set.get("pinned_components", instruction_set.get("pinnedComponents", {})) or {})
+    for key, component in (instruction_set.get("components") or {}).items():
+        body, pin = _instruction_component(component)
+        if body is not None:
+            components[key] = body
+        elif pin is not None:
+            pinned_components[key] = pin
+    payload = {
+        "name": instruction_set.get("name"),
+        "model_config": instruction_set.get("model_config", instruction_set.get("modelConfig")),
+        "shape": instruction_set.get("shape"),
+        **({"model_config_settings_version_id": instruction_set["model_config_settings_version_id"]} if isinstance(instruction_set.get("model_config_settings_version_id"), str) else {}),
+        **({"prompt_component_key": instruction_set["prompt_component_key"]} if isinstance(instruction_set.get("prompt_component_key"), str) else {}),
+        "components": components,
+    }
+    if pinned_components:
+        payload["pinned_components"] = pinned_components
+    return payload
+
+
 def _bounded_stream(value: str) -> str:
     encoded = value.encode("utf-8", errors="replace")
     if len(encoded) <= MAX_RUNNER_OUTPUT_BYTES:
@@ -102,6 +251,7 @@ def run_file_contract_runner(
     prompt_version_id: str,
     runner_version_id: str,
     run_id: str | None,
+    prompt_body_present: bool = True,
     timeout_seconds: int = DEFAULT_RUNNER_TIMEOUT_SECONDS,
     extra_payload: dict[str, Any] | None = None,
 ) -> RunnerCallResult:
@@ -114,26 +264,37 @@ def run_file_contract_runner(
     with tempfile.TemporaryDirectory(prefix="orizu-gepa-call-") as temp_dir:
         input_path = Path(temp_dir) / "input.json"
         output_path = Path(temp_dir) / "output.json"
+        instruction_set = (extra_payload or {}).get("instruction_set")
+        instruction_set_dir = Path(temp_dir) / "instruction-set" if isinstance(instruction_set, dict) else None
+        if instruction_set_dir is not None:
+            _write_instruction_set_layout(instruction_set_dir, instruction_set)
         # Extra payload first: the core file-contract keys are authoritative
         # and never overridable by adapter-supplied companions.
+        prompt = {
+            "body_kind": body_kind,
+            "provider_settings": provider_settings,
+        }
+        # The exec-context response decides whether this key exists. Runners
+        # mirror it; no local shape heuristic may silently remove body bytes.
+        if prompt_body_present:
+            prompt["body"] = prompt_body
+        payload_extra = dict(extra_payload or {})
+        if isinstance(instruction_set, dict):
+            payload_extra["instruction_set"] = _runner_instruction_set_payload(instruction_set)
         input_path.write_text(json.dumps({
-            **(extra_payload or {}),
+            **payload_extra,
             "row": row,
-            "prompt": {
-                "body": prompt_body,
-                "body_kind": body_kind,
-                "provider_settings": provider_settings,
-            },
+            "prompt": prompt,
             "prompt_version_id": prompt_version_id,
             "runner_version_id": runner_version_id,
             "run_id": run_id,
-        }, ensure_ascii=False))
+        }, ensure_ascii=False), encoding="utf-8")
 
         try:
             result = subprocess.run(
                 command,
                 cwd=runner_path,
-                env=_runner_env(input_path, output_path),
+                env=_runner_env(input_path, output_path, instruction_set_dir),
                 text=True,
                 capture_output=True,
                 check=False,
@@ -152,7 +313,7 @@ def run_file_contract_runner(
             raise RuntimeError(
                 f"Runner failed with exit code {result.returncode}: {stderr or stdout}"
             )
-        data = json.loads(output_path.read_text())
+        data = json.loads(output_path.read_text(encoding="utf-8"))
         known = {
             "model_response",
             "raw_api_response",
@@ -175,16 +336,46 @@ def run_file_contract_runner(
 
 
 def make_candidate_runner(runner_dir: str | Path, run_id: str | None):
-    def _run(candidate_text: str, row: DatasetRow, prompt_context: PromptContext, candidate_id: str) -> RunnerCallResult:
+    def _run(candidate_text: str | dict[str, str], row: DatasetRow, prompt_context: PromptContext, candidate_id: str) -> RunnerCallResult:
+        instruction_set = prompt_context.instruction_set
+        if instruction_set:
+            is_tuple_rewrite = isinstance(candidate_text, dict) and len(candidate_text) > 1
+            if not isinstance(candidate_text, dict):
+                prompt_component_key = instruction_set.get("prompt_component_key")
+                candidate_components = {prompt_component_key: candidate_text} if isinstance(prompt_component_key, str) else None
+            else:
+                candidate_components = candidate_text
+            if not candidate_components or not all(isinstance(key, str) and isinstance(value, str) for key, value in candidate_components.items()):
+                raise RuntimeError("instruction_set_candidate_component_unresolvable")
+            instruction_set = dict(instruction_set)
+            existing_components = dict(instruction_set.get("components") or {})
+            pinned_components = dict(instruction_set.get("pinned_components") or {})
+            if not set(candidate_components).issubset(set(existing_components) | set(pinned_components)):
+                raise RuntimeError("instruction_set_candidate_component_unresolvable")
+            instruction_set["components"] = {
+                **existing_components,
+                **candidate_components,
+            }
+            for key in candidate_components:
+                pinned_components.pop(key, None)
+            instruction_set["pinned_components"] = pinned_components
+            # The candidate is the execution contract. Legacy string rewrites
+            # preserve the body the server supplied; only a genuine tuple
+            # rewrite omits it.
+            prompt_body = None if is_tuple_rewrite else candidate_text
+        else:
+            prompt_body = candidate_text
         return run_file_contract_runner(
             runner_dir=runner_dir,
             row=row.row,
-            prompt_body=candidate_text,
+            prompt_body=prompt_body,
             body_kind=prompt_context.body_kind,
             provider_settings=prompt_context.provider_settings,
             prompt_version_id=prompt_context.prompt_version_id,
             runner_version_id=prompt_context.runner_version_id,
             run_id=run_id,
+            prompt_body_present=not instruction_set or not is_tuple_rewrite,
+            extra_payload={"instruction_set": instruction_set} if instruction_set else None,
         )
     return _run
 
@@ -318,10 +509,13 @@ def make_scorer_runner(
                 "candidate_raw_response": candidate_result.raw_api_response,
                 "candidate_error": candidate_result.error,
             }
+        if scorer_context.instruction_set:
+            extra_payload = {**(extra_payload or {}), "instruction_set": scorer_context.instruction_set}
         return run_file_contract_runner(
             runner_dir=runner_dir,
             row=scorer_row,
             prompt_body=scorer_context.body,
+            prompt_body_present=scorer_context.body_present,
             body_kind=scorer_context.body_kind,
             provider_settings=scorer_context.provider_settings,
             prompt_version_id=scorer_context.prompt_version_id,

package/vendor/skills/orizu-cli/SKILL.md

@@ -152,7 +152,8 @@ Local execution workflow:
 
 Bundled `run-gepa` reflection behavior:
 - **Scorer contract:** `run-gepa` sends the scorer runner a GEPA-shaped row (`{source_row, candidate_id, candidate_output, …}`), NOT the flat-row shape used by `runners exec --scorer-version`. A judge runner built for flat-row score runs will silently score every candidate 0 unless you pass `--scorer-input-contract flat_row` (add `--scorer-candidate-field <row-field>`, e.g. `draft`, when the judge reads the candidate output from a named row field). Do not hand-write an adapter runner — the flag applies the official adapter without changing the registered runner bytes, so it composes with `--scorer-runner-dir` content-sha verification. `run-gepa` validates the contract on the seed at launch and refuses a uniformly-worst-scoring seed with a diagnosis; `--allow-degenerate-seed` overrides only when the seed genuinely deserves the worst score everywhere. Both contracts: `references/prompt-control-plane.md` ("Scorer-Runner Input Contracts").
-- Budget controls are mutually exclusive. Use at most one of `--budget auto|light|medium|heavy`, `--max-metric-calls <n>`, `--max-full-evals <n>`, or `--max-iterations <n>`. If none is provided, `run-gepa` uses `--budget auto`, the balanced medium preset.
+- Budget controls are mutually exclusive. Use 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>`. The proposal cap is official-engine-only. If none is provided, `run-gepa` uses `--budget auto`, the balanced medium preset.
+- **Skilled proposer:** opt in with `--candidate-proposer skilled-proposer` on the official engine; the selected run prepares or reuses its managed Python environment automatically. Bound proposal work with `--proposal-max-tokens` and `--proposal-max-calls`, independently of `--max-metric-calls`. Read `references/prompt-control-plane.md` ("Skilled proposer") for validation and recovery; readiness is proven when optimizer execution begins without an `ALI_1505_*` environment diagnostic.
 - The reflective LM's final text is used verbatim as the next candidate prompt. It should return only the complete updated prompt body, not analysis, labels, XML tags, or markdown fences.
 - Keep provider-native reasoning controls separate from the prompt text with `--reflection-provider-settings <json|@file>`.
 - Reflection max-token limits are explicit config, not implicit defaults. Use `--reflection-max-tokens <n>` when a provider requires an output cap; this maps to Anthropic `max_tokens` and OpenAI `max_output_tokens`.
@@ -175,6 +176,7 @@ Detailed walkthrough — GEPA mechanics, Orizu-tracked optimization, optional DS
 - `references/building-apps.md` — labeler app contract, design principles, common patterns, offline smoke test.
 - `references/building-judges.md` — judge/scorer authoring + TPR/TNR validation.
 - `references/optimization-with-gepa.md` — GEPA optimization loop, with DSPy only as external context.
+- `references/migrate-existing-gepa-setup.md` — migrating a customer's existing official-GEPA script into Orizu, ending in `orizu scorers verify-parity` before any optimization.
 - `references/optimization-reports.md` — report template, GEPA diagnostics, kappa/confusion-matrix guidance, and next-step recommendations.
 - `scripts/test-app.mjs` — smoke test for `App.tsx` + schemas before `orizu apps create` (runs on plain `node`).
 

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

@@ -77,6 +77,65 @@ orizu projects list --team my-team
 orizu projects create --name "Quality Eval" --team my-team
 ```
 
+### Instruction sets
+
+```bash
+orizu instruction-sets list --project my-team/quality-eval [--status active|archived|all] [--json]
+orizu instruction-sets show <set> --project my-team/quality-eval [--status active|archived|all] [--json]
+orizu instruction-sets create ./orizu.instruction-set.json --project my-team/quality-eval [--runner-version <id>] [--model-config <identity>] [--json]
+orizu instruction-sets push ./orizu.instruction-set.json --project my-team/quality-eval [--runner-version <id>] [--json]
+orizu instruction-sets sync <set> --out ./instructions --project my-team/quality-eval [--model-config <identity>] [--json]
+orizu instruction-sets profiles new <set> --project my-team/quality-eval --model-config <identity> [--json]
+orizu instruction-sets profiles promote <set> --project my-team/quality-eval --model-config <identity> --version <n> [--json]
+orizu instruction-sets profiles rollback <set> --project my-team/quality-eval --model-config <identity> --to <n> [--json]
+orizu instruction-sets default show <set> --project my-team/quality-eval [--json]
+orizu instruction-sets default move <set> --project my-team/quality-eval --model-config <identity> --version <n> [--json]
+orizu instruction-sets shape add <set> --project my-team/quality-eval --key <key> --from <manifest> [--json]
+orizu instruction-sets shape remove <set> --project my-team/quality-eval --key <key> [--json]
+```
+
+`list` returns each instruction set and its ordered shape. `show` returns the
+default and every model-config profile's production state. `create` and `push`
+read a local manifest; JSON output is one document per line.
+
+`profiles new` copies the default component map into a model-config profile without
+changing its production resolution; hosted agents may create this seed because
+it does not move production. `profiles promote` moves that profile to a
+version, and `profiles rollback` creates a new version copied from `--to`,
+including that target version's settings version, before moving production.
+These label-moving commands are human-only. For a single-component set that
+wraps a prompt, only default-profile promote and rollback also move the wrapped
+prompt's production label in the same transaction and print `default profile →
+prompt label`. This coupling is one-way: moving the prompt label directly does
+not repoint the profile.
+
+`default show` reports the default and the model configs that currently resolve
+to it. `default move` is human-only and first reads that impact before moving
+the pointer to a sealed, commit-anchored profile version. `shape add` and
+`shape remove` create a new complete version for every profile; they never move
+the default or a production label. The set does not resolve for affected model
+configs until those pointers move to the new shape-change profile versions; the
+text CLI prints the required follow-up commands.
+
+The manifest is a JSON object with `name`, ordered `shape`, and `components`.
+Every component supplies `{ key, text }` or `{ key, path }`; paths are relative
+to the manifest. Set-wide components must cover the complete shape. A component
+may add `modelConfig` for a profile override: `create` materializes that named
+profile with the set-wide component map plus its overrides, while `push` updates named
+profiles already present on the set. `push` refuses a manifest whose shape
+differs from the stored set.
+
+`sync` writes `<out>/<set>/manifest.json`, `default/<key>.md`, and
+`profiles/<identity-slug>/<key>.md` for offline execution. TypeScript runners
+use `loadInstructionSet(dir, name, modelConfigIdentity)` from `orizu`; Python
+runners use `orizu_gepa_connector.instruction_set_loader.load_instruction_set`.
+Both select that model config's production component map or the default without a
+network call. Git-pinned components have no local bytes: loading one raises
+`instruction_set_component_unavailable` until the runner supplies those bytes.
+An existing manifest file that cannot be read is instead
+`instruction_set_component_unreadable`, which means re-sync or repair disk
+state rather than supplying a Git-pinned component.
+
 ### Apps
 
 ```bash
@@ -156,6 +215,18 @@ orizu datasets clone --dataset <datasetId|datasetUrl> --name "Batch 1 Copy"
 
 Dataset version and split-set commands used by prompt runs are covered in `prompt-control-plane.md`.
 
+### Model configs
+
+```bash
+orizu model-configs create azure/gpt-5.4-mini --settings @settings.json --project my-team/quality-eval
+orizu model-configs list --project my-team/quality-eval --json
+orizu model-configs show azure/gpt-5.4-mini --project my-team/quality-eval
+orizu model-configs settings set azure/gpt-5.4-mini --settings '{"temperature":0.3}' --project my-team/quality-eval
+orizu model-configs copy openai/gpt-5.4-mini --to azure/gpt-5.4-mini --project my-team/quality-eval
+```
+
+Model identities are lowercase `provider/model` values and unique within a project. Creating a config creates settings version 1 (with `{}` when `--settings` is omitted). `settings set` appends a settings version and advances the current pointer; `copy` snapshots the source’s current settings and display name into version 1 for the new identity. `--settings` accepts a JSON object or `@file`; all commands support `--json`.
+
 Supported file types:
 - `.csv`
 - `.json` (array of objects)
@@ -310,7 +381,7 @@ exist.
 Optimization trace commands:
 
 ```bash
-orizu optimizations run-gepa ... [--scorer-input-contract gepa|flat_row] [--scorer-candidate-field <row-field>] [--allow-degenerate-seed] [--num-threads auto|N] [--reflection-retry-attempts 3] [--reflection-http-timeout-seconds 180] [--log-dir logs] [--no-local-log]
+orizu optimizations run-gepa ... [--scorer-input-contract gepa|flat_row] [--scorer-candidate-field <row-field>] [--allow-degenerate-seed] [--candidate-selection-strategy pareto|current_best|epsilon_greedy] [--epsilon N] [--objective <text>] [--candidate-proposer skilled-proposer] [--proposal-max-calls N] [--proposal-max-tokens N] [--python <command>] [--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
 ```
@@ -319,6 +390,7 @@ Behavior:
 - `run-gepa` sends the scorer runner a GEPA-shaped row (`{source_row, candidate_output, …}`) by default. Judge runners written for flat-row score runs (`runners exec --scorer-version`) need `--scorer-input-contract flat_row` (plus `--scorer-candidate-field <row-field>` when the judge reads the candidate output from a named row field) or they silently score everything 0. `run-gepa` validates the contract on the seed at launch and refuses a uniformly-worst seed unless `--allow-degenerate-seed` is set. See `prompt-control-plane.md` ("Scorer-Runner Input Contracts").
 - `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.
+- The skilled proposer is official-engine-only and prepares its managed Python environment on the selected run. Flag validation, proposal budgets, and recovery: `prompt-control-plane.md` ("Skilled proposer").
 - `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.
@@ -407,3 +479,15 @@ Hugging Face / external dataset auth:
 Worker assignment reads are self-only:
 - Regular members cannot see other assignees' queues or response payloads.
 - Use `tasks status` and `tasks export` for operator-side reporting.
+### Offline instruction-set sync
+
+`orizu instruction-sets sync <set> --project <team/project> --out <dir>` writes
+an atomic local manifest. A resolver failure for either the default or any
+selected profile refuses the entire sync as `instruction_set_unresolvable`; the
+route never silently downgrades a failed production component map to default bytes. A
+filtered `--model-config` sync records `filteredTo`, and a loader must refuse an
+identity excluded by that marker with `instruction_set_profile_not_synced`.
+
+Use `import { loadInstructionSet } from 'orizu/instruction-set-loader'` for the
+small typed TypeScript loader surface; Python uses
+`from orizu_gepa_connector import load_instruction_set`.