gatewaysdk 0.3.2__py3-none-any.whl

gatewaysdk/cli/platform.py

@@ -0,0 +1,4086 @@
+# Copyright (c) Gateway. All rights reserved.
+
+"""Gateway platform CLI — register agents and manage algorithms.
+
+Entry point: `gateway` (registered in pyproject.toml).
+
+Usage::
+
+    gateway deploy <image> [--manifest-dir ./gateway_manifest] [--skip-build]
+    gateway algorithm list
+    gateway algorithm new <name>
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from dataclasses import asdict
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+try:
+    import typer
+except ImportError:
+    print(
+        "typer is required for the gateway CLI. Install with: pip install typer",
+        file=sys.stderr,
+    )
+    sys.exit(1)
+
+try:
+    import httpx
+except ImportError:
+    print(
+        "httpx is required for the gateway CLI. Install with: pip install httpx",
+        file=sys.stderr,
+    )
+    sys.exit(1)
+
+app = typer.Typer(
+    name="gateway",
+    help="Gateway platform CLI — register agents and manage algorithms.",
+    no_args_is_help=True,
+)
+
+# =============================================================================
+# deploy command
+# =============================================================================
+
+
+@app.command()
+def deploy(
+    image: Optional[str] = typer.Argument(
+        None,
+        help="Docker image to register. If omitted, builds from project dir.",
+    ),
+    project_dir: str = typer.Option(
+        ".",
+        "--project-dir",
+        help="Agent project directory (for building).",
+    ),
+    manifest_dir: str = typer.Option(
+        "./gateway_manifest",
+        help="Path to the gateway_manifest/ directory.",
+    ),
+    skip_build: bool = typer.Option(
+        False,
+        "--skip-build",
+        help="Skip Docker build, register image only.",
+    ),
+    dockerfile: Optional[str] = typer.Option(
+        None,
+        "--dockerfile",
+        help="Use specific Dockerfile (e.g., Dockerfile.gpu).",
+    ),
+    tag: Optional[str] = typer.Option(
+        None,
+        "--tag",
+        help="Override image tag.",
+    ),
+    dry_run: bool = typer.Option(
+        False,
+        "--dry-run",
+        help="Validate manifest only, don't build or register.",
+    ),
+    host: Optional[str] = typer.Option(
+        None,
+        envvar="GATEWAY_HOST",
+        help="Gateway server URL (e.g., http://localhost:3000).",
+    ),
+    api_key: Optional[str] = typer.Option(
+        None,
+        envvar="GATEWAY_SECRET_KEY",
+        help="Gateway project API key (sk-lf-...).",
+    ),
+) -> None:
+    """Build, push, and register an agent with the Gateway platform.
+
+    Examples::
+
+        # Full pipeline: build + push + register
+        gateway deploy --tag myagent:v1
+
+        # Register pre-built image (skip build)
+        gateway deploy myregistry/myagent:v1 --skip-build
+
+        # Use specific Dockerfile
+        gateway deploy --tag myagent:v1 --dockerfile Dockerfile.gpu
+
+        # Validate manifest only
+        gateway deploy --dry-run
+    """
+    from gatewaysdk.platform.manifest import parse_manifest, parse_secrets, parse_task_schema
+
+    manifest_path = Path(manifest_dir)
+    if not manifest_path.exists():
+        typer.echo(f"Error: Manifest directory not found: {manifest_path}", err=True)
+        raise typer.Exit(1)
+
+    # Parse manifest
+    try:
+        manifest = parse_manifest(manifest_path)
+    except (FileNotFoundError, ValueError) as e:
+        typer.echo(f"Error parsing manifest: {e}", err=True)
+        raise typer.Exit(1)
+
+    # Parse optional task schema
+    task_schema = parse_task_schema(manifest_path)
+
+    typer.echo(f"Validating manifest...")
+    typer.echo(f"  Name: {manifest.name}")
+    typer.echo(f"  Version: {manifest.version}")
+    typer.echo(f"  Capabilities: {', '.join(manifest.capabilities) or 'none'}")
+    if task_schema:
+        typer.echo(f"  Task schema: found")
+
+    if dry_run:
+        typer.echo("Dry-run complete. Manifest is valid.")
+        return
+
+    # Determine image tag
+    image_tag = image or tag
+    if not image_tag and not skip_build:
+        image_tag = f"{manifest.name}:latest"
+
+    # Build if needed
+    if not skip_build and not image:
+        from gatewaysdk.platform.builder import build_image, detect_build_strategy
+
+        proj = Path(project_dir)
+        strategy = detect_build_strategy(proj, dockerfile)
+        typer.echo(f"\nBuilding image '{image_tag}' (strategy: {strategy.value})...")
+
+        try:
+            image_tag = build_image(proj, image_tag, dockerfile=dockerfile)
+            typer.echo(f"  Built successfully!")
+        except (RuntimeError, FileNotFoundError) as e:
+            typer.echo(f"Build failed: {e}", err=True)
+            raise typer.Exit(1)
+
+        # Extract image digest for pinning
+        from gatewaysdk.platform.builder import get_image_digest
+
+        image_digest = get_image_digest(image_tag)
+
+    if not image_tag:
+        typer.echo("Error: No image specified. Provide an image argument or use --tag.", err=True)
+        raise typer.Exit(1)
+
+    # Resolve credentials (from flags, env, or config)
+    from gatewaysdk.cli.http_client import get_credentials
+
+    resolved_host, resolved_public, resolved_secret = get_credentials(host, api_key)
+
+    typer.echo(f"\nRegistering agent '{manifest.name}' with image '{image_tag}'...")
+
+    # Build request payload (includes runner/resource config from agent.yml)
+    from dataclasses import asdict
+
+    # image_digest is set during build; not available for --skip-build
+    _digest = locals().get("image_digest")
+
+    payload: dict = {
+        "name": manifest.name,
+        "image": image_tag,
+        "manifest": {
+            "version": manifest.version,
+            "capabilities": manifest.capabilities,
+            "resources": manifest.resources,
+            "description": manifest.description,
+            "runner": asdict(manifest.runner),
+            "resource_limits": asdict(manifest.resource_limits),
+            "env": manifest.env,
+        },
+        "capabilities": manifest.capabilities,
+        "resources": {
+            **manifest.resources,
+            "runner": asdict(manifest.runner),
+            "resource_limits": asdict(manifest.resource_limits),
+        },
+        "description": manifest.description,
+    }
+
+    if _digest is not None:
+        payload["imageDigest"] = _digest
+
+    if task_schema is not None:
+        payload["taskInputSchema"] = task_schema.input_schema
+
+    # POST to Gateway
+    url = f"{resolved_host.rstrip('/')}/api/public/agents/register"
+    try:
+        response = httpx.post(
+            url,
+            json=payload,
+            auth=(resolved_public, resolved_secret),
+            timeout=30.0,
+        )
+    except httpx.RequestError as e:
+        typer.echo(f"Error connecting to {resolved_host}: {e}", err=True)
+        raise typer.Exit(1)
+
+    if response.status_code == 201:
+        data = response.json()
+        typer.echo(f"Agent registered successfully!")
+        typer.echo(f"  ID: {data.get('id')}")
+        typer.echo(f"  Name: {data.get('name')}")
+        typer.echo(f"  Compatible algorithms: {', '.join(data.get('compatibleAlgorithms', []))}")
+    else:
+        typer.echo(f"Registration failed (HTTP {response.status_code}):", err=True)
+        try:
+            typer.echo(f"  {json.dumps(response.json(), indent=2)}", err=True)
+        except Exception:
+            typer.echo(f"  {response.text}", err=True)
+        raise typer.Exit(1)
+
+    # Upload secrets from gateway_manifest/.env (if present)
+    secrets = parse_secrets(manifest_path)
+    if secrets:
+        typer.echo(f"\nUploading {len(secrets)} secret(s)...")
+        secrets_client = httpx.Client(
+            base_url=resolved_host.rstrip("/"),
+            auth=(resolved_public, resolved_secret),
+            timeout=15.0,
+        )
+        for secret_name, secret_value in secrets.items():
+            try:
+                # Try create first
+                resp = secrets_client.post(
+                    "/api/public/secrets",
+                    json={"name": secret_name, "value": secret_value, "scope": "agent"},
+                )
+                if resp.status_code in (200, 201):
+                    typer.echo(f"  {secret_name} (created)")
+                elif resp.status_code == 409:
+                    # Already exists — update
+                    resp = secrets_client.put(
+                        f"/api/public/secrets/{secret_name}",
+                        json={"value": secret_value, "scope": "agent"},
+                    )
+                    if resp.status_code in (200, 201):
+                        typer.echo(f"  {secret_name} (updated)")
+                    else:
+                        typer.echo(f"  {secret_name} (update failed: HTTP {resp.status_code})", err=True)
+                else:
+                    typer.echo(f"  {secret_name} (failed: HTTP {resp.status_code})", err=True)
+            except Exception as e:
+                typer.echo(f"  {secret_name} (error: {e})", err=True)
+        secrets_client.close()
+
+
+# =============================================================================
+# init command — scaffold agent project
+# =============================================================================
+
+_DOCKERFILE_TEMPLATE = """\
+# Auto-generated by `gateway init`
+FROM python:3.12-slim
+
+RUN apt-get update && apt-get install -y --no-install-recommends \\
+    build-essential \\
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+
+# Install Python dependencies
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Install gatewaysdk with agent extras (includes gateway-agent CLI)
+RUN pip install --no-cache-dir "gatewaysdk[agent]"
+
+# Copy agent code
+COPY . /app/agent/
+
+ENV PYTHONPATH="/app:/app/agent"
+
+# gateway-agent handles: store client, tracer, runner init, rollout polling
+CMD ["gateway-agent", "--agent", "{agent_ref}"]
+"""
+
+_AGENT_YML_TEMPLATE = """\
+# Agent manifest for Gateway Platform
+# Generated by `gateway init`
+
+name: {name}
+version: "1.0.0"
+description: >
+  {description}
+
+capabilities:
+  - prompt-optimization
+  - tool-use
+
+runner:
+  n_runners: 1
+  poll_interval: 5.0
+
+resources:
+  memory: "4g"
+  cpu: 1.0
+  gpu: false
+
+env: {{}}
+"""
+
+
+@app.command()
+def init(
+    agent_ref: str = typer.Option(
+        ...,
+        "--agent",
+        "-a",
+        help="Agent reference in module:attribute format (e.g., crm_agent:crm_agent).",
+    ),
+    name: Optional[str] = typer.Option(
+        None,
+        "--name",
+        "-n",
+        help="Agent name. Defaults to module name.",
+    ),
+    output_dir: str = typer.Option(
+        ".",
+        "--output-dir",
+        "-o",
+        help="Output directory for generated files.",
+    ),
+) -> None:
+    """Scaffold a Gateway agent project with Dockerfile and manifest.
+
+    Generates:
+    - Dockerfile with gateway-agent entrypoint
+    - gateway_manifest/agent.yml with default configuration
+
+    Examples::
+
+        gateway init --agent crm_agent:crm_agent
+        gateway init --agent my_agent:agent --name my-cool-agent
+    """
+    output = Path(output_dir)
+
+    # Derive name from module if not provided
+    module_name = agent_ref.split(":")[0]
+    agent_name = name or module_name.replace("_", "-")
+    description = f"Gateway agent: {agent_name}"
+
+    # Generate Dockerfile
+    dockerfile_path = output / "Dockerfile"
+    if dockerfile_path.exists():
+        typer.echo(f"Warning: {dockerfile_path} already exists, skipping.")
+    else:
+        dockerfile_content = _DOCKERFILE_TEMPLATE.format(agent_ref=agent_ref)
+        dockerfile_path.write_text(dockerfile_content)
+        typer.echo(f"Created {dockerfile_path}")
+
+    # Generate manifest
+    manifest_dir = output / "gateway_manifest"
+    manifest_dir.mkdir(parents=True, exist_ok=True)
+    agent_yml_path = manifest_dir / "agent.yml"
+    if agent_yml_path.exists():
+        typer.echo(f"Warning: {agent_yml_path} already exists, skipping.")
+    else:
+        agent_yml_content = _AGENT_YML_TEMPLATE.format(
+            name=agent_name,
+            description=description,
+        )
+        agent_yml_path.write_text(agent_yml_content)
+        typer.echo(f"Created {agent_yml_path}")
+
+    # Generate .gitignore (includes gateway_manifest/.env)
+    gitignore_path = output / ".gitignore"
+    gitignore_entry = "gateway_manifest/.env"
+    if gitignore_path.exists():
+        existing = gitignore_path.read_text()
+        if gitignore_entry not in existing:
+            with open(gitignore_path, "a") as f:
+                f.write(f"\n# Gateway secrets (API keys)\n{gitignore_entry}\n")
+            typer.echo(f"Updated {gitignore_path} (added {gitignore_entry})")
+    else:
+        gitignore_path.write_text(f"# Gateway secrets (API keys — never commit)\n{gitignore_entry}\n")
+        typer.echo(f"Created {gitignore_path}")
+
+    # Generate sample .env in gateway_manifest/
+    env_path = manifest_dir / ".env"
+    if not env_path.exists():
+        env_path.write_text(
+            "# API keys for the agent container\n"
+            "# These are uploaded to the platform as encrypted secrets during `gateway deploy`\n"
+            "# ANTHROPIC_API_KEY=sk-ant-...\n"
+            "# OPENAI_API_KEY=sk-...\n"
+        )
+        typer.echo(f"Created {env_path} (sample — add your API keys)")
+
+    typer.echo(f"\nAgent project scaffolded!")
+    typer.echo(f"  Agent ref: {agent_ref}")
+    typer.echo(f"  Name: {agent_name}")
+    typer.echo(f"\nNext steps:")
+    typer.echo(f"  1. Add your agent code and requirements.txt")
+    typer.echo(f"  2. Add API keys to gateway_manifest/.env")
+    typer.echo(f"  3. Build & deploy: gateway deploy --tag {agent_name}:latest")
+
+
+# =============================================================================
+# algorithm subcommands
+# =============================================================================
+
+algorithm_app = typer.Typer(
+    name="algorithm",
+    help="List and manage algorithms.",
+    no_args_is_help=True,
+)
+app.add_typer(algorithm_app, name="algorithm")
+
+
+@algorithm_app.command("list")
+def algorithm_list() -> None:
+    """List all available algorithms from class metadata."""
+    from gatewaysdk.algorithm.base import Algorithm
+
+    subclasses = Algorithm.__subclasses__()
+    if not subclasses:
+        typer.echo("No algorithms found. Import algorithm modules first.")
+        return
+
+    typer.echo(f"{'Name':<12} {'Display':<16} {'GPU':<6} {'Description'}")
+    typer.echo("-" * 70)
+    for cls in subclasses:
+        gpu = cls.requirements.get("gpu", False) if cls.requirements else False
+        typer.echo(f"{cls.name:<12} {cls.display_name:<16} {str(gpu):<6} {cls.description}")
+
+
+@algorithm_app.command("new")
+def algorithm_new(
+    name: str = typer.Argument(..., help="Algorithm name (e.g., my_algo)"),
+    output_dir: str = typer.Option(".", help="Directory to create the algorithm in"),
+) -> None:
+    """Scaffold a new algorithm class."""
+    output_path = Path(output_dir) / f"{name}.py"
+    if output_path.exists():
+        typer.echo(f"Error: {output_path} already exists.", err=True)
+        raise typer.Exit(1)
+
+    template = f'''"""Custom algorithm: {name}."""
+
+from __future__ import annotations
+
+from typing import Any, ClassVar, Dict, Optional
+
+from gatewaysdk.algorithm.base import Algorithm
+from gatewaysdk.types import Dataset
+
+
+class {name.title().replace("_", "")}(Algorithm):
+    """TODO: Describe your algorithm."""
+
+    name: ClassVar[str] = "{name}"
+    display_name: ClassVar[str] = "{name.title().replace("_", " ")}"
+    description: ClassVar[str] = "TODO: Add description"
+    requirements: ClassVar[Dict[str, Any]] = {{"gpu": False, "min_runners": 1}}
+
+    def run(
+        self,
+        train_dataset: Optional[Dataset[Any]] = None,
+        val_dataset: Optional[Dataset[Any]] = None,
+    ) -> None:
+        trainer = self.get_trainer()
+        store = self.get_store()
+
+        # TODO: Implement your algorithm logic here
+        raise NotImplementedError("Implement run() for {name}")
+'''
+
+    output_path.write_text(template)
+    typer.echo(f"Created algorithm scaffold: {output_path}")
+
+
+# =============================================================================
+# auth commands
+# =============================================================================
+
+auth_app = typer.Typer(
+    name="auth",
+    help="Manage authentication credentials.",
+    no_args_is_help=True,
+)
+app.add_typer(auth_app, name="auth")
+
+
+@auth_app.command("login")
+def auth_login(
+    host: str = typer.Option(..., prompt=True, help="Gateway server URL"),
+    public_key: str = typer.Option(..., prompt=True, help="Project public key (pk-lf-...)"),
+    api_key: str = typer.Option(..., prompt=True, hide_input=True, help="Project secret key (sk-lf-...)"),
+) -> None:
+    """Store credentials for the gateway CLI."""
+    from gatewaysdk.cli.http_client import save_config
+
+    save_config({"host": host.rstrip("/"), "public_key": public_key, "api_key": api_key})
+    typer.echo("Credentials saved to ~/.gateway/config.json")
+
+
+@auth_app.command("logout")
+def auth_logout() -> None:
+    """Clear stored credentials."""
+    from gatewaysdk.cli.http_client import CONFIG_FILE
+
+    if CONFIG_FILE.exists():
+        CONFIG_FILE.unlink()
+        typer.echo("Credentials cleared.")
+    else:
+        typer.echo("No credentials stored.")
+
+
+@auth_app.command("status")
+def auth_status() -> None:
+    """Show current authentication status."""
+    from gatewaysdk.cli.http_client import get_config
+
+    config = get_config()
+    host = config.get("host")
+    has_key = bool(config.get("api_key"))
+
+    if host:
+        typer.echo(f"Host: {host}")
+        typer.echo(f"API key: {'configured' if has_key else 'not set'}")
+    else:
+        typer.echo("No credentials stored. Run `gateway auth login`.")
+
+
+# =============================================================================
+# secret commands
+# =============================================================================
+
+secret_app = typer.Typer(
+    name="secret",
+    help="Manage project secrets (encrypted env vars for agent containers).",
+    no_args_is_help=True,
+)
+app.add_typer(secret_app, name="secret")
+
+
+@secret_app.command("set")
+def secret_set(
+    name: str = typer.Argument(..., help="Secret name (UPPER_SNAKE_CASE, e.g. TAVILY_API_KEY)"),
+    value: Optional[str] = typer.Option(
+        None,
+        "--value",
+        "-v",
+        help="Secret value. If omitted, you will be prompted.",
+    ),
+    description: Optional[str] = typer.Option(None, "--description", "-d", help="Human-readable description"),
+    scope: str = typer.Option("agent", help="Scope: agent, worker, or both"),
+    host: Optional[str] = typer.Option(None, envvar="GATEWAY_HOST"),
+    api_key: Optional[str] = typer.Option(None, envvar="GATEWAY_SECRET_KEY"),
+) -> None:
+    """Create or update a project secret."""
+    from gatewaysdk.cli.http_client import create_client
+
+    if value is None:
+        value = typer.prompt("Secret value", hide_input=True)
+
+    client = create_client(host, api_key)
+    payload: dict = {"name": name, "value": value, "scope": scope}
+    if description:
+        payload["description"] = description
+
+    response = client.post("/api/public/secrets", json=payload)
+
+    if response.status_code in (200, 201):
+        data = response.json()
+        typer.echo(f"Secret '{data.get('name', name)}' saved ({data.get('displayValue', '****')})")
+    elif response.status_code == 409:
+        # Already exists -- update
+        response = client.put(f"/api/public/secrets/{name}", json=payload)
+        if response.status_code in (200, 201):
+            typer.echo(f"Secret '{name}' updated.")
+        else:
+            typer.echo(f"Failed (HTTP {response.status_code}): {response.text}", err=True)
+            raise typer.Exit(1)
+    else:
+        typer.echo(f"Failed (HTTP {response.status_code}): {response.text}", err=True)
+        raise typer.Exit(1)
+
+
+@secret_app.command("list")
+def secret_list(
+    host: Optional[str] = typer.Option(None, envvar="GATEWAY_HOST"),
+    api_key: Optional[str] = typer.Option(None, envvar="GATEWAY_SECRET_KEY"),
+) -> None:
+    """List project secrets (names and descriptions only, not values)."""
+    from gatewaysdk.cli.http_client import create_client
+
+    client = create_client(host, api_key)
+    response = client.get("/api/public/secrets")
+
+    if response.status_code == 200:
+        secrets = response.json().get("secrets", [])
+        if not secrets:
+            typer.echo("No secrets configured. Run `gateway secret set <name>` to add one.")
+            return
+        typer.echo(f"{'Name':<30} {'Scope':<10} {'Description'}")
+        typer.echo("-" * 70)
+        for s in secrets:
+            desc = (s.get("description") or "")[:28]
+            typer.echo(f"{s.get('name', ''):<30} {s.get('scope', ''):<10} {desc}")
+    else:
+        typer.echo(f"Failed (HTTP {response.status_code}): {response.text}", err=True)
+        raise typer.Exit(1)
+
+
+@secret_app.command("delete")
+def secret_delete(
+    name: str = typer.Argument(..., help="Secret name to delete"),
+    host: Optional[str] = typer.Option(None, envvar="GATEWAY_HOST"),
+    api_key: Optional[str] = typer.Option(None, envvar="GATEWAY_SECRET_KEY"),
+) -> None:
+    """Delete a project secret."""
+    from gatewaysdk.cli.http_client import create_client
+
+    client = create_client(host, api_key)
+    response = client.delete(f"/api/public/secrets/{name}")
+
+    if response.status_code in (200, 204):
+        typer.echo(f"Secret '{name}' deleted.")
+    else:
+        typer.echo(f"Failed (HTTP {response.status_code}): {response.text}", err=True)
+        raise typer.Exit(1)
+
+
+# =============================================================================
+# agent commands
+# =============================================================================
+
+agent_app = typer.Typer(
+    name="agent",
+    help="Manage registered agents.",
+    no_args_is_help=True,
+)
+app.add_typer(agent_app, name="agent")
+
+
+@agent_app.command("list")
+def agent_list(
+    host: Optional[str] = typer.Option(None, envvar="GATEWAY_HOST"),
+    api_key: Optional[str] = typer.Option(None, envvar="GATEWAY_SECRET_KEY"),
+) -> None:
+    """List registered agents."""
+    from gatewaysdk.cli.http_client import create_client
+
+    client = create_client(host, api_key)
+    response = client.get("/api/public/agents")
+
+    if response.status_code == 200:
+        data = response.json()
+        agents = data.get("agents", [])
+        if not agents:
+            typer.echo("No agents registered. Run `gateway deploy` to register an agent.")
+            return
+        typer.echo(f"{'Name':<20} {'Image':<30} {'Compatible'}")
+        typer.echo("-" * 70)
+        for a in agents:
+            compat = ", ".join(a.get("compatibleAlgorithms", []))
+            typer.echo(f"{a.get('name', ''):<20} {a.get('image', '')[:28]:<30} {compat}")
+    else:
+        typer.echo(f"Failed (HTTP {response.status_code}): {response.text}", err=True)
+        raise typer.Exit(1)
+
+
+# =============================================================================
+# run commands
+# =============================================================================
+
+run_app = typer.Typer(
+    name="run",
+    help="Manage platform optimization runs.",
+    no_args_is_help=True,
+)
+app.add_typer(run_app, name="run")
+
+
+@run_app.command("start")
+def run_start(
+    algorithm: str = typer.Argument(..., help="Algorithm name (e.g., gepa)"),
+    agent_id: str = typer.Option(..., "--agent", help="Registered agent ID"),
+    dataset_id: str = typer.Option(..., "--dataset", help="Dataset ID"),
+    name: Optional[str] = typer.Option(None, "--name", help="Run name"),
+    config_json: Optional[str] = typer.Option(None, "--config", help="JSON config string"),
+    host: Optional[str] = typer.Option(None, envvar="GATEWAY_HOST"),
+    api_key: Optional[str] = typer.Option(None, envvar="GATEWAY_SECRET_KEY"),
+) -> None:
+    """Start a platform optimization run."""
+    from gatewaysdk.cli.http_client import create_client
+
+    client = create_client(host, api_key)
+
+    payload: dict = {
+        "algorithmName": algorithm,
+        "agentId": agent_id,
+        "datasetId": dataset_id,
+    }
+    if name:
+        payload["name"] = name
+    if config_json:
+        payload["config"] = json.loads(config_json)
+
+    response = client.post("/api/public/runs/start", json=payload)
+
+    if response.status_code in (200, 201):
+        data = response.json()
+        typer.echo(f"Run started!")
+        typer.echo(f"  Run ID: {data.get('runId')}")
+        typer.echo(f"  Run #:  {data.get('runNumber')}")
+        typer.echo(f"  Job ID: {data.get('jobId')}")
+        typer.echo(f"  Status: {data.get('status')}")
+    else:
+        typer.echo(f"Failed (HTTP {response.status_code}):", err=True)
+        typer.echo(f"  {response.text}", err=True)
+        raise typer.Exit(1)
+
+
+@run_app.command("verify")
+def run_verify(
+    algorithm: str = typer.Argument(..., help="Algorithm name"),
+    agent_id: str = typer.Option(..., "--agent", help="Agent ID"),
+    dataset_id: Optional[str] = typer.Option(None, "--dataset", help="Dataset ID"),
+    host: Optional[str] = typer.Option(None, envvar="GATEWAY_HOST"),
+    api_key: Optional[str] = typer.Option(None, envvar="GATEWAY_SECRET_KEY"),
+) -> None:
+    """Verify an algorithm configuration."""
+    from gatewaysdk.cli.http_client import create_client
+
+    client = create_client(host, api_key)
+    payload: dict = {"algorithmName": algorithm, "agentId": agent_id}
+    if dataset_id:
+        payload["datasetId"] = dataset_id
+
+    response = client.post("/api/public/runs/verify", json=payload)
+
+    if response.status_code in (200, 202):
+        data = response.json()
+        typer.echo(f"Verify job queued: {data.get('jobId')}")
+    else:
+        typer.echo(f"Failed (HTTP {response.status_code}): {response.text}", err=True)
+        raise typer.Exit(1)
+
+
+@run_app.command("list")
+def run_list(
+    source: Optional[str] = typer.Option(None, help="Filter by source (platform/sdk)"),
+    limit: int = typer.Option(20, help="Max results"),
+    host: Optional[str] = typer.Option(None, envvar="GATEWAY_HOST"),
+    api_key: Optional[str] = typer.Option(None, envvar="GATEWAY_SECRET_KEY"),
+) -> None:
+    """List runs."""
+    from gatewaysdk.cli.http_client import create_client
+
+    client = create_client(host, api_key)
+    params: dict = {"limit": str(limit)}
+    if source:
+        params["source"] = source
+
+    response = client.get("/api/public/runs", params=params)
+
+    if response.status_code == 200:
+        data = response.json()
+        runs = data.get("runs", [])
+        if not runs:
+            typer.echo("No runs found.")
+            return
+        typer.echo(f"{'#':<6} {'Name':<30} {'State':<12} {'Source':<10}")
+        typer.echo("-" * 60)
+        for r in runs:
+            typer.echo(
+                f"{r.get('runNumber', ''):<6} "
+                f"{(r.get('name') or '')[:28]:<30} "
+                f"{r.get('state', ''):<12} "
+                f"{r.get('source', ''):<10}"
+            )
+    else:
+        typer.echo(f"Failed (HTTP {response.status_code}): {response.text}", err=True)
+        raise typer.Exit(1)
+
+
+# =============================================================================
+# dataset commands
+# =============================================================================
+
+dataset_app = typer.Typer(
+    name="dataset",
+    help="Manage datasets.",
+    no_args_is_help=True,
+)
+app.add_typer(dataset_app, name="dataset")
+
+
+@dataset_app.command("upload")
+def dataset_upload(
+    path: str = typer.Argument(..., help="Path to JSON or JSONL file"),
+    name: str = typer.Option(..., "--name", help="Dataset name"),
+    agent: Optional[str] = typer.Option(
+        None,
+        "--agent",
+        help="Validate items against this agent's task schema",
+    ),
+    description: Optional[str] = typer.Option(None, help="Description"),
+    host: Optional[str] = typer.Option(None, envvar="GATEWAY_HOST"),
+    api_key: Optional[str] = typer.Option(None, envvar="GATEWAY_SECRET_KEY"),
+) -> None:
+    """Upload a JSON or JSONL file as a dataset.
+
+    Supports:
+      - JSON with {"tasks": [...]} or {"items": [...]} wrapper
+      - JSON bare array [item1, item2, ...]
+      - JSONL (one JSON object per line)
+
+    Examples::
+
+        gateway dataset upload tasks.json --name crm-benchmark-v1
+        gateway dataset upload tasks.json --name crm-v1 --agent crm-analyst
+        gateway dataset upload tasks.jsonl --name eval-set
+    """
+    from gatewaysdk.cli.http_client import create_client
+
+    file_path = Path(path)
+    if not file_path.exists():
+        typer.echo(f"Error: File not found: {path}", err=True)
+        raise typer.Exit(1)
+
+    # Read items -- auto-detect JSON vs JSONL
+    with open(file_path) as f:
+        raw = f.read().strip()
+
+    if file_path.suffix == ".json" or raw.startswith("{") or raw.startswith("["):
+        data = json.loads(raw)
+        if isinstance(data, list):
+            items = data
+        elif isinstance(data, dict):
+            items = data.get("tasks") or data.get("items") or []
+        else:
+            items = []
+    else:
+        # JSONL: one item per line
+        items = [json.loads(line) for line in raw.splitlines() if line.strip()]
+
+    if not items:
+        typer.echo("Error: No items found in file.", err=True)
+        raise typer.Exit(1)
+
+    typer.echo(f"Found {len(items)} items in {file_path.name}")
+
+    # Schema validation against agent's taskInputSchema
+    if agent:
+        client = create_client(host, api_key)
+        resp = client.get("/api/public/agents")
+        if resp.status_code != 200:
+            typer.echo(f"Warning: Could not fetch agents for validation: HTTP {resp.status_code}", err=True)
+        else:
+            agents_list = resp.json().get("agents", [])
+            matched = [a for a in agents_list if a.get("name") == agent]
+            if not matched:
+                typer.echo(f"Warning: Agent '{agent}' not found, skipping validation", err=True)
+            else:
+                schema = matched[0].get("taskInputSchema")
+                if schema:
+                    try:
+                        import jsonschema
+                    except ImportError:
+                        typer.echo(
+                            "Warning: jsonschema not installed, skipping validation. "
+                            "Install with: pip install jsonschema",
+                            err=True,
+                        )
+                        schema = None
+
+                    if schema:
+                        typer.echo(f"Validating against agent '{agent}' schema...")
+                        errors = []
+                        for i, item in enumerate(items):
+                            try:
+                                jsonschema.validate(item, schema)
+                            except jsonschema.ValidationError as e:
+                                item_name = item.get("name", f"item {i}") if isinstance(item, dict) else f"item {i}"
+                                errors.append(f"  [{i+1}/{len(items)}] {item_name}: {e.message}")
+                        if errors:
+                            typer.echo(f"Validation failed ({len(errors)} errors):", err=True)
+                            for e in errors[:10]:
+                                typer.echo(e, err=True)
+                            if len(errors) > 10:
+                                typer.echo(f"  ... and {len(errors) - 10} more", err=True)
+                            raise typer.Exit(1)
+                        typer.echo(f"  All {len(items)} items valid.")
+                else:
+                    typer.echo(f"Agent '{agent}' has no taskInputSchema, skipping validation")
+
+    # Upload
+    typer.echo(f"Uploading {len(items)} items as dataset '{name}'...")
+
+    client = create_client(host, api_key)
+    payload: dict = {
+        "name": name,
+        "items": [{"input": item} for item in items],
+    }
+    if description:
+        payload["description"] = description
+
+    response = client.post("/api/public/datasets/import", json=payload)
+
+    if response.status_code in (200, 201):
+        data = response.json()
+        typer.echo(f"Dataset created!")
+        typer.echo(f"  Dataset ID: {data.get('datasetId')}")
+        typer.echo(f"  Name:       {data.get('datasetName')}")
+        typer.echo(f"  Items:      {data.get('itemCount')}")
+    else:
+        typer.echo(f"Failed (HTTP {response.status_code}): {response.text}", err=True)
+        raise typer.Exit(1)
+
+
+bench_app = typer.Typer(
+    name="bench",
+    help="Benchmark container hub — version and push benchmark environments to Gateway.",
+    no_args_is_help=True,
+)
+app.add_typer(bench_app, name="bench")
+
+
+def _ci_finish(
+    result: dict,
+    *,
+    fail_under: Optional[float],
+    bar_source: str = "--fail-under",
+    title: str,
+    facts: Optional[List[tuple]] = None,
+) -> None:
+    """Shared CI affordances for every eval command: a GitHub Actions step
+    summary whenever Actions provides one ($GITHUB_STEP_SUMMARY), then the
+    reward gate. The gate is honest by construction: asking for a bar on a
+    result that carries no aggregate reward exits 1, same as a miss — a gate
+    that cannot measure must not pass."""
+    import os
+
+    metrics = result.get("metrics") if isinstance(result.get("metrics"), dict) else {}
+    avg = metrics.get("avg_reward") if metrics else None
+    if avg is None and isinstance(result.get("reward"), (int, float)):
+        avg = result["reward"]
+
+    summary_path = os.environ.get("GITHUB_STEP_SUMMARY")
+    if summary_path:
+        try:
+            rows: List[tuple] = [("avg reward", "n/a" if avg is None else f"{avg:.3f}")]
+            n = (metrics or {}).get("n") or result.get("samples")
+            if n is not None:
+                rows.append(("samples", str(n)))
+            if result.get("evaluationId"):
+                rows.append(("evaluation", str(result["evaluationId"])))
+            rows.extend(facts or [])
+            if fail_under is not None:
+                verdict = "PASS" if (avg is not None and avg >= fail_under) else "FAIL"
+                rows.append(("gate", f"{verdict} — bar {fail_under:g} ({bar_source})"))
+            lines = [f"### {title}", "", "| | |", "|---|---|"]
+            lines += [f"| {k} | {v} |" for k, v in rows]
+            with open(summary_path, "a") as fh:
+                fh.write("\n".join(lines) + "\n\n")
+        except OSError:
+            pass  # the summary is a nicety; the gate below is the contract
+
+    if fail_under is None:
+        return
+    if avg is None:
+        typer.echo(
+            f"gate: the result carries no aggregate reward — cannot verify "
+            f"the {fail_under:g} bar ({bar_source}), failing.",
+            err=True,
+        )
+        raise typer.Exit(1)
+    if avg < fail_under:
+        typer.echo(
+            f"gate: avg reward {avg:.3f} is below the {fail_under:g} bar " f"({bar_source}).",
+            err=True,
+        )
+        raise typer.Exit(1)
+    typer.echo(
+        f"gate: avg reward {avg:.3f} clears the {fail_under:g} bar " f"({bar_source}).",
+        err=True,
+    )
+
+
+worlds_app = typer.Typer(
+    help="Run agents against simulated worlds (world-over-tools dev loop).",
+    no_args_is_help=True,
+)
+app.add_typer(worlds_app, name="worlds")
+
+
+def _resolve_agent_callable(spec: str):
+    """``file.py[:fn]`` or ``module.path[:fn]``; the attr defaults to
+    ``agent``. Returns the callable or raises typer.Exit with the reason."""
+    import importlib
+    import importlib.util
+    import os
+
+    target, _, attr = spec.partition(":")
+    attr = attr or "agent"
+    looks_like_file = target.endswith(".py") or os.sep in target
+    if looks_like_file or Path(target).is_file():
+        file_path = Path(target).resolve()
+        if not file_path.is_file():
+            typer.echo(f"agent file not found: {target}", err=True)
+            raise typer.Exit(1)
+        module_spec = importlib.util.spec_from_file_location(file_path.stem, file_path)
+        if module_spec is None or module_spec.loader is None:
+            typer.echo(f"could not load agent file: {target}", err=True)
+            raise typer.Exit(1)
+        module = importlib.util.module_from_spec(module_spec)
+        module_spec.loader.exec_module(module)
+    else:
+        try:
+            module = importlib.import_module(target)
+        except ImportError as exc:
+            typer.echo(f"could not import agent module '{target}': {exc}", err=True)
+            raise typer.Exit(1)
+    fn = getattr(module, attr, None)
+    if not callable(fn):
+        typer.echo(
+            f"'{spec}' does not expose a callable '{attr}' — point --agent at "
+            "a function taking the world (file.py:fn or module:fn; fn "
+            "defaults to 'agent')",
+            err=True,
+        )
+        raise typer.Exit(1)
+    return fn
+
+
+@worlds_app.command("ci")
+def worlds_ci(
+    path: str = typer.Option(".", "--path", "-p", help="World directory inside the checked-out repo."),
+    model: str = typer.Option(..., "--model", "-m", help="Model id for the runner."),
+    agent: str = typer.Option(
+        "mini-swe-agent",
+        "--agent",
+        "-a",
+        help="harbor agent that runs the tasks (use `oracle` for a deterministic regression check of the world itself).",
+    ),
+    branch: Optional[str] = typer.Option(
+        None,
+        "--branch",
+        "-b",
+        help="Hub branch to push and run. Defaults to GITHUB_HEAD_REF (PRs), then GITHUB_REF_NAME (pushes), then the dir's recorded branch.",
+    ),
+    fail_under: Optional[float] = typer.Option(
+        None,
+        "--fail-under",
+        min=0.0,
+        max=1.0,
+        help="Reward gate. Defaults to the world's own pass bar, then 0.7.",
+    ),
+    no_push: bool = typer.Option(
+        False,
+        "--no-push",
+        help="Run the dir's recorded base version as-is (requires a clean checkout) instead of pushing the working tree.",
+    ),
+    num_examples: int = typer.Option(-1, "--num-examples", "-n"),
+    rollouts: int = typer.Option(1, "--rollouts-per-example", "-r"),
+    message: Optional[str] = typer.Option(
+        None, "--message", "-M", help="Push change reason (default: a CI commit line)."
+    ),
+    output_dir: str = typer.Option("./outputs", "--output-dir", "-o"),
+    host: Optional[str] = typer.Option(None, "--host", envvar="GATEWAY_HOST"),
+) -> None:
+    """The PR-to-simulation gate in ONE command, built for GitHub Actions:
+
+        gateway worlds ci --path environments/drive-sim -m openai/gpt-4o-mini
+
+    Pushes the checked-out world onto a hub branch named after the PR
+    (GITHUB_HEAD_REF), runs its tasks as a harbor world (docker), files
+    the run pinned to the pushed version — branch-tagged, PR chip included
+    when the world links a repo — writes a $GITHUB_STEP_SUMMARY table, and
+    exits 1 when the average reward lands below the bar. The bar defaults to
+    the world's own pass threshold, so the job fails exactly when the
+    platform would mark the run failed.
+
+    Needs GATEWAY_HOST / GATEWAY_PUBLIC_KEY / GATEWAY_SECRET_KEY and
+    OPENROUTER_API_KEY in the environment (repo secrets), plus docker.
+    """
+    import os
+
+    from gatewaysdk.benchmark_hub import (
+        GatewayBenchmarkClient,
+        GatewayEvalsClient,
+        detect_env_kind,
+        find_mcp_config,
+        harvest_job_dir,
+        local_tree_state,
+        read_local_meta,
+        resolve_harbor_model,
+        run_harbor_job,
+        tasks_root,
+    )
+
+    src = os.path.abspath(path)
+    if not os.path.isdir(src):
+        typer.echo(f"--path is not a directory: {path}", err=True)
+        raise typer.Exit(1)
+    resolved_kind = detect_env_kind(src)
+    if resolved_kind == "mock-tools":
+        _reject_mock_tools()
+    if resolved_kind in ("verifiers", "verifiers-v1"):
+        typer.echo(
+            "`worlds ci` runs harbor worlds (self-grading task dirs); this "
+            "dir is a verifiers package — use `gateway bench eval` instead.",
+            err=True,
+        )
+        raise typer.Exit(1)
+
+    api_key = os.environ.get("OPENROUTER_API_KEY")
+    if not api_key:
+        typer.echo("OPENROUTER_API_KEY is required for `worlds ci`.", err=True)
+        raise typer.Exit(1)
+
+    meta = read_local_meta(Path(src)) or {}
+    ci_branch = (
+        branch
+        or os.environ.get("GITHUB_HEAD_REF")
+        or os.environ.get("GITHUB_REF_NAME")
+        or meta.get("branch")
+        or meta.get("ref")
+    )
+    if not ci_branch:
+        typer.echo(
+            "no branch to run: pass --branch, or run under GitHub Actions "
+            "(GITHUB_HEAD_REF / GITHUB_REF_NAME), or push the dir once so "
+            ".gateway records one.",
+            err=True,
+        )
+        raise typer.Exit(1)
+
+    bench = GatewayBenchmarkClient.from_env(host)
+    if no_push:
+        # Run exactly what the dir's base names — refuse a drifted tree, a
+        # pin to code that did not run would fabricate provenance.
+        state = local_tree_state(Path(src))
+        if not (state["clean"] and meta.get("versionId")):
+            typer.echo(
+                "--no-push needs a clean checkout with a recorded base " "(.gateway) — push first, or drop --no-push.",
+                err=True,
+            )
+            raise typer.Exit(1)
+        version_id = str(meta["versionId"])
+        slug = str(meta.get("slug") or os.path.basename(src))
+        content_hash = str(meta.get("contentHash") or "")
+    else:
+        sha = os.environ.get("GITHUB_SHA", "")[:12]
+        repo = os.environ.get("GITHUB_REPOSITORY", "")
+        push_message = message or (f"[ci] {repo}@{sha}" if repo and sha else "[ci] working tree")
+        # Force: the hub branch MIRRORS this checkout (the PR's code). A
+        # concurrent tip on the same branch is by definition stale here.
+        pushed = bench.push(src, branch=ci_branch, force=True, message=push_message)
+        version_id = str(pushed["versionId"])
+        slug = str(pushed["slug"])
+        content_hash = str(pushed.get("contentHash") or "")
+        typer.echo(f"pushed {slug}@{ci_branch} ({content_hash[:8]})", err=True)
+
+    bar_source = "--fail-under"
+    if fail_under is None:
+        try:
+            resolved = bench.resolve_version(slug, ci_branch)
+            world_bar = resolved.get("passThreshold")
+        except Exception:
+            world_bar = None
+        if isinstance(world_bar, (int, float)):
+            fail_under, bar_source = float(world_bar), "world pass bar"
+        else:
+            fail_under, bar_source = 0.7, "default bar"
+
+    harbor_model = resolve_harbor_model(model, agent)
+    jobs_dir = os.path.join(output_dir, "harbor-jobs", f"ci--{slug}--{ci_branch.replace('/', '-')}")
+    run_harbor_job(
+        tasks_root(src),
+        jobs_dir,
+        model=harbor_model,
+        agent=agent,
+        num_examples=num_examples,
+        rollouts_per_example=rollouts,
+        extra_env={"OPENROUTER_API_KEY": api_key},
+        mcp_config=find_mcp_config(src),
+    )
+    result = harvest_job_dir(
+        jobs_dir,
+        version_id,
+        GatewayEvalsClient.from_env(host),
+        model=harbor_model,
+        rollouts_per_example=rollouts,
+    )
+    result["branch"] = ci_branch
+    result["versionId"] = version_id
+    typer.echo(json.dumps(result, indent=2))
+    _ci_finish(
+        result,
+        fail_under=fail_under,
+        bar_source=bar_source,
+        title=f"World sim · {slug}@{ci_branch}",
+        facts=[
+            ("model", harbor_model),
+            ("agent", agent),
+            ("version", content_hash[:8] or version_id[:8]),
+        ],
+    )
+
+
+@worlds_app.command("run")
+def worlds_run(
+    slug: Optional[str] = typer.Argument(
+        None,
+        help="World slug@ref to pull and run against; omit when using --path.",
+    ),
+    path: Optional[str] = typer.Option(
+        None,
+        "--path",
+        "-p",
+        help="Local world directory instead of a hub pull (a `bench checkout`, or any bundle dir). A clean checkout files runs pinned to its base version; a drifted or unlinked dir runs unfiled.",
+    ),
+    variant: Optional[str] = typer.Option(None, "--variant", "-v", help="World variation (task variant) to load."),
+    agent: str = typer.Option(
+        ...,
+        "--agent",
+        "-a",
+        help="Agent callable: file.py[:fn] or module:fn (fn defaults to 'agent'). Called as fn(world); use world.tools / world.wrap inside.",
+    ),
+    model: str = typer.Option(
+        "sdk-dev-loop",
+        "--model",
+        "-m",
+        help="Model label recorded on the filed run.",
+    ),
+    no_file: bool = typer.Option(False, "--no-file", help="Run and grade locally without filing an evaluation."),
+    fail_under: Optional[float] = typer.Option(
+        None,
+        "--fail-under",
+        min=0.0,
+        max=1.0,
+        help="CI gate: exit 1 when the graded reward lands below this bar. Writes a $GITHUB_STEP_SUMMARY table under GitHub Actions.",
+    ),
+    host: Optional[str] = typer.Option(None, "--host", envvar="GATEWAY_HOST"),
+) -> None:
+    """Run an agent function against one variation of a world and (by
+    default) file the graded result as a version-pinned, branch-tagged run —
+    the CLI face of ``gatewaysdk.worlds``:
+
+        gateway worlds run google-drive-sim@fix/retention-lock \
+            --variant alice --agent my_agent.py -m "claude-sonnet-4-5"
+
+        gateway worlds run --path ./google-drive-sim --variant alice \
+            --agent my_agent.py
+
+    The agent is any callable taking the loaded world; its tool calls go
+    through the world's handlers over the variation's seeded database, and
+    the task's own grader scores the end state.
+    """
+    from gatewaysdk import worlds
+    from gatewaysdk.worlds import WorldError
+
+    if (slug is None) == (path is None):
+        typer.echo("pass exactly one of SLUG or --path", err=True)
+        raise typer.Exit(1)
+
+    agent_fn = _resolve_agent_callable(agent)
+    try:
+        world = (
+            worlds.load(slug, variant=variant, host=host)
+            if slug is not None
+            else worlds.load_path(path, variant=variant)
+        )
+    except WorldError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(1)
+
+    if world.file_block and not no_file:
+        # Say it BEFORE the agent runs, not after: the run still executes and
+        # grades, only the filing is off.
+        typer.echo(f"note: running unfiled — {world.file_block}", err=True)
+    try:
+        result = world.run(
+            agent_fn,
+            model=model,
+            file=not no_file and world.version_id is not None,
+            host=host,
+        )
+    except WorldError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(1)
+    result["world"] = {
+        "slug": world.slug,
+        "branch": world.branch,
+        "versionId": world.version_id,
+        "variant": world.variant,
+        "filed": "evaluationId" in result,
+    }
+    typer.echo(json.dumps(result, indent=2))
+    _ci_finish(
+        result,
+        fail_under=fail_under,
+        title=f"World run · {world.slug or 'local'}"
+        + (f"@{world.branch}" if world.branch else "")
+        + f" · {world.variant}",
+        facts=[("model", model)],
+    )
+
+
+session_app = typer.Typer(
+    help="Live world sessions with api/ui/browser surfaces (the CLI face of gatewaysdk.world_sessions).",
+    no_args_is_help=True,
+)
+worlds_app.add_typer(session_app, name="session")
+
+schema_app = typer.Typer(help="Compile and check offline executable world schemas")
+worlds_app.add_typer(schema_app, name="schema")
+
+
+@schema_app.command("init")
+def schema_init(
+    path: Path = typer.Argument(..., help="New or empty directory for the world"),
+    connector: str = typer.Option(
+        "custom",
+        help="Connector template slug; `custom` is the blank contract, `workspace:<slug>` a workspace connector "
+        "pulled from the platform. `gateway worlds schema templates` lists what is installed.",
+    ),
+    name: Optional[str] = typer.Option(None, help="Environment name and package id"),
+    host: Optional[str] = typer.Option(None, "--host", envvar="GATEWAY_HOST", help="For workspace: connectors"),
+):
+    """Initialize a schema world from a connector template, then compile it."""
+    from gatewaysdk.environment.schema.__main__ import main
+
+    if connector.startswith("workspace:"):
+        _schema_init_from_workspace(path, connector[len("workspace:") :], name, host)
+        return
+    argv = ["init", str(path), "--connector", connector]
+    if name:
+        argv += ["--name", name]
+    main(argv)
+
+
+def _schema_init_from_workspace(path: Path, slug: str, name: Optional[str], host: Optional[str]) -> None:
+    """The template comes from the platform's copy of the connector, files inline."""
+    from gatewaysdk.connectors import GatewayConnectorsError
+    from gatewaysdk.environment.schema import ContractError
+    from gatewaysdk.environment.schema.scaffold import init_bundle_from_files
+
+    if not slug:
+        raise typer.BadParameter("workspace:<slug> needs the connector's slug")
+    try:
+        pulled = _connectors_client(host).pull(slug)
+    except GatewayConnectorsError as error:
+        typer.echo(str(error), err=True)
+        raise typer.Exit(1)
+    files = {relative: content.encode("utf-8") for relative, content in pulled["files"].items()}
+    try:
+        contract = init_bundle_from_files(path, files, connector=slug, name=name)
+    except ContractError as error:
+        typer.echo(json.dumps({"status": "rejected", "error": error.detail}, sort_keys=True))
+        raise typer.Exit(1)
+    commit = pulled["commit"].get("commitHash") or pulled["commit"].get("id")
+    typer.echo(
+        json.dumps(
+            {"status": "ok", "domain": contract.target, "connector": {"slug": slug, "commit": commit}}, sort_keys=True
+        )
+    )
+
+
+@schema_app.command("templates")
+def schema_templates():
+    """List the installed connector templates; `custom` is always offered last."""
+    from gatewaysdk.environment.schema import list_templates
+
+    for slug in list_templates():
+        typer.echo(slug)
+
+
+@schema_app.command("compile")
+def schema_compile(path: Path = typer.Argument(...)):
+    from gatewaysdk.environment.schema.__main__ import main
+
+    main(["compile", str(path)])
+
+
+@schema_app.command("check")
+def schema_check(path: Path = typer.Argument(...)):
+    from gatewaysdk.environment.schema.__main__ import main
+
+    main(["check", str(path)])
+
+
+@schema_app.command("describe")
+def schema_describe(path: Path = typer.Argument(...)):
+    from gatewaysdk.environment.schema.__main__ import main
+
+    main(["describe", str(path)])
+
+
+connector_app = typer.Typer(help="Describe a vendor connection, capture what it returns, seed the world from it")
+worlds_app.add_typer(connector_app, name="connector")
+
+
+def _pairs(values: List[str], what: str) -> Dict[str, str]:
+    out: Dict[str, str] = {}
+    for item in values:
+        if "=" not in item:
+            raise typer.BadParameter(f"{what} must look like name=value, got {item!r}")
+        key, value = item.split("=", 1)
+        out[key.strip()] = value
+    return out
+
+
+@connector_app.command("validate")
+def connector_validate(path: Path = typer.Argument(..., help="World directory holding connector.toml")):
+    """Parse connector.toml and list its operations."""
+    from gatewaysdk.environment.schema.connector import load_spec
+
+    spec = load_spec(path)
+    typer.echo(f"{spec.slug}  {spec.base_url}  auth={spec.scheme}")
+    for op in spec.operations.values():
+        target = f" -> {op.entity}" if op.entity else ""
+        typer.echo(f"  {op.name}: {op.method} {op.path}{target}")
+
+
+@connector_app.command("capture")
+def connector_capture(
+    path: Path = typer.Argument(..., help="World directory holding connector.toml"),
+    op: str = typer.Option(..., "--op", help="Operation name from connector.toml"),
+    arg: List[str] = typer.Option([], "--arg", help="Path argument, name=value (repeatable)"),
+    param: List[str] = typer.Option([], "--param", help="Query parameter, name=value (repeatable)"),
+    max_pages: Optional[int] = typer.Option(None, help="Override [capture].max_pages"),
+    remote: bool = typer.Option(
+        False,
+        "--remote",
+        help="Run the capture on the platform (from its allow-listed egress, with the environment's "
+        "secret) and pull the pages into captures/ here.",
+    ),
+    environment: Optional[str] = typer.Option(
+        None, "--environment", help="Environment slug or id for --remote (default: the world's directory name)"
+    ),
+    timeout: int = typer.Option(900, "--timeout", help="Seconds to wait for a --remote capture"),
+    host: Optional[str] = typer.Option(None, "--host", envvar="GATEWAY_HOST"),
+):
+    """Call the live connection once (following its cursor) and record every page under captures/.
+
+    The credential comes from the environment variable named in [auth].secret_env and is
+    never written to disk; recorded bodies are redacted per [redact]. With --remote the
+    platform makes the calls instead — from the pod whose IP the vendor allow-listed, with
+    the credential held as the environment's secret (`gateway bench secrets set`) — and
+    the same redacted pages land in captures/ here, ready for `connector ingest`.
+    """
+    if remote:
+        written = _remote_capture(
+            path, op, _pairs(arg, "--arg"), _pairs(param, "--param"), max_pages, environment, timeout, host
+        )
+    else:
+        from gatewaysdk.environment.schema.connector import capture
+
+        written = capture(path, op, _pairs(arg, "--arg"), _pairs(param, "--param"), max_pages=max_pages)
+    for file in written:
+        typer.echo(file.relative_to(path).as_posix())
+
+
+def _remote_capture(
+    world: Path,
+    op: str,
+    args: Dict[str, str],
+    params: Dict[str, str],
+    max_pages: Optional[int],
+    environment: Optional[str],
+    timeout: int,
+    host: Optional[str],
+) -> List[Path]:
+    """The platform runs the operation; the pages come home through the file drive."""
+    import time as _time
+
+    from gatewaysdk.environment.schema.connector import CAPTURES, MANIFEST, load_spec
+    from gatewaysdk.environments import GatewayEnvironmentClient
+
+    load_spec(world)  # the same refusals the platform would give, before a round trip
+    spec_text = (world / "connector.toml").read_text(encoding="utf-8")
+    client = GatewayEnvironmentClient.from_env(host)
+    container_id = _resolve_environment_id(client, environment or world.resolve().name)
+    request_id = client.start_connector_capture(
+        container_id, connector_toml=spec_text, op=op, args=args, params=params, max_pages=max_pages
+    )
+    typer.echo(f"# remote capture {request_id} on {container_id}", err=True)
+    deadline = _time.time() + timeout
+    while True:
+        view = client.get_connector_capture(container_id, request_id)
+        stage = view.get("stage")
+        if stage == "complete":
+            break
+        if stage in ("failed", "cancelled"):
+            typer.echo(f"Remote capture {stage}: {view.get('error') or 'no detail'}", err=True)
+            raise typer.Exit(1)
+        if _time.time() >= deadline:
+            typer.echo(
+                f"Remote capture still {stage} after {timeout}s; poll it with the request id {request_id}", err=True
+            )
+            raise typer.Exit(1)
+        _time.sleep(5)
+    slug_prefix = f"worlds/{view['worldSlug']}/"
+    written: List[Path] = []
+    for file in view.get("files", []):
+        drive_path = str(file["path"])
+        relative = drive_path[len(slug_prefix) :] if drive_path.startswith(slug_prefix) else drive_path
+        if not relative.startswith(f"{CAPTURES}/") or ".." in relative:
+            typer.echo(f"Refusing a capture outside captures/: {drive_path}", err=True)
+            raise typer.Exit(1)
+        destination = world / relative
+        destination.parent.mkdir(parents=True, exist_ok=True)
+        destination.write_bytes(client.read_file(container_id, drive_path))
+        written.append(destination)
+    manifest_path = world / CAPTURES / MANIFEST
+    existing = json.loads(manifest_path.read_text(encoding="utf-8")) if manifest_path.is_file() else []
+    known = {entry.get("file") for entry in existing if isinstance(entry, dict)}
+    for entry in view.get("manifest", []):
+        if isinstance(entry, dict) and entry.get("file") not in known:
+            existing.append(entry)
+            known.add(entry.get("file"))
+    manifest_path.parent.mkdir(parents=True, exist_ok=True)
+    manifest_path.write_text(json.dumps(existing, indent=1, sort_keys=True) + "\n", encoding="utf-8")
+    return written
+
+
+@connector_app.command("conform")
+def connector_conform(
+    path: Path = typer.Argument(..., help="World directory holding connector.toml"),
+    openapi: list[Path] = typer.Option(
+        ..., "--openapi", help="The vendor's OpenAPI document (JSON or YAML); repeatable"
+    ),
+    out: Optional[Path] = typer.Option(None, "--out", help="Write the full report as JSON here"),
+    limit: Optional[int] = typer.Option(None, "--limit", help="Check only the first N operations"),
+):
+    """Serve the world and check every operation's answer against the vendor's OpenAPI:
+    the documented status, and a body the vendor's response schema accepts."""
+    from gatewaysdk.environment.schema.conform import conform
+
+    report = conform(path, [str(p) for p in openapi], max_operations=limit)
+    for outcome in report.outcomes:
+        if not outcome.documented:
+            mark = "  ?  "
+        elif outcome.ok:
+            mark = "  ok "
+        else:
+            mark = " FAIL"
+        detail = "" if outcome.documented else "not in the document"
+        if outcome.documented and outcome.status is not None and str(outcome.status) not in outcome.expected:
+            detail = f"status {outcome.status}, vendor documents {', '.join(outcome.expected)}"
+        elif outcome.problems:
+            detail = outcome.problems[0] + (f" (+{len(outcome.problems) - 1})" if len(outcome.problems) > 1 else "")
+        typer.echo(f"{mark} {outcome.method:6} {outcome.path:60} {outcome.operation}  {detail}")
+    typer.echo(json.dumps(report.summary))
+    if out is not None:
+        out.write_text(json.dumps(report.to_json(), indent=1) + "\n")
+        typer.echo(f"report: {out}")
+    summary = report.summary
+    raise typer.Exit(1 if summary["status_mismatch"] or summary["schema_violations"] else 0)
+
+
+@connector_app.command("ingest")
+def connector_ingest(
+    path: Path = typer.Argument(..., help="World directory holding captures/"),
+    batch_id: Optional[str] = typer.Option(None, help="Batch id; defaults to the next initial version"),
+):
+    """Seed data/initial.json from the successful captures, gated by the world's contract."""
+    from gatewaysdk.environment.schema.connector import ingest
+
+    result = ingest(path, batch_id=batch_id)
+    typer.echo(f"batch {result['batch']}: {result['mutations']} mutations")
+    for entity, count in sorted(result["entity_counts"].items()):
+        typer.echo(f"  {entity}: {count}")
+
+
+# ── workspace connectors: the template as an object on the platform ──────────
+
+
+def _connectors_client(host: Optional[str]):
+    from gatewaysdk.connectors import GatewayConnectorsClient
+
+    return GatewayConnectorsClient.from_env(host)
+
+
+@connector_app.command("publish")
+def connector_publish(
+    path: Path = typer.Argument(..., help="A connector template directory, or the world directory it was authored in"),
+    slug: Optional[str] = typer.Option(None, "--slug", help="Connector slug (default: the directory name)"),
+    message: Optional[str] = typer.Option(None, "--message", "-m", help="Commit message"),
+    description: Optional[str] = typer.Option(None, "--description", help="One-line description shown in listings"),
+    tag: List[str] = typer.Option([], "--tag", help="Tag (repeatable)"),
+    workspace_visible: bool = typer.Option(
+        False, "--workspace-visible", help="Visible to the whole workspace, not only this project's members"
+    ),
+    project_scope: bool = typer.Option(False, "--project-scope", help="Own it in this project rather than the org"),
+    host: Optional[str] = typer.Option(None, "--host", envvar="GATEWAY_HOST"),
+):
+    """Save the template as a workspace connector: created on first publish, a new commit after.
+
+    A world directory is mapped back into the template layout (schema/world.json → world.json,
+    tools/handlers.py → handlers.py, …); data/, captures/, db/ and generated files stay behind.
+    The platform compiles the template before accepting it and refuses one that does not make a
+    world. The published connector equals the directory: paths no longer present are removed.
+    """
+    from gatewaysdk.connectors import GatewayConnectorsError, collect_template
+
+    try:
+        gathered = collect_template(path)
+    except (FileNotFoundError, ValueError) as error:
+        typer.echo(str(error), err=True)
+        raise typer.Exit(1)
+    slug = slug or path.resolve().name
+    client = _connectors_client(host)
+    files: Dict[str, Optional[str]] = dict(gathered.files)
+    parent: Optional[str] = None
+    try:
+        if client.exists(slug):
+            head = client.pull(slug)
+            for stale in sorted(set(head["files"]) - set(files)):
+                files[stale] = None
+                typer.echo(f"# removing {stale}", err=True)
+            head_hash = head["commit"].get("commitHash")
+            parent = head_hash if isinstance(head_hash, str) and len(head_hash) >= 8 else None
+        for left in gathered.skipped:
+            typer.echo(f"# left behind: {left}", err=True)
+        result = client.push(
+            slug,
+            files,
+            message=message or f"publish {slug}",
+            parent_commit=parent,
+            description=description,
+            tags=tag or None,
+            workspace_visible=workspace_visible,
+            scope="project" if project_scope else "org",
+        )
+    except GatewayConnectorsError as error:
+        typer.echo(str(error), err=True)
+        raise typer.Exit(1)
+    commit = result.get("commitHash") or result.get("commitId") or ""
+    typer.echo(f"{result.get('status', 'committed')} {slug} {commit} {result.get('url', '')}".rstrip())
+
+
+def _table(rows: List[List[str]], header: List[str]) -> str:
+    widths = [max(len(str(cell)) for cell in column) for column in zip(header, *rows)]
+    lines = [header] + rows
+    return "\n".join("  ".join(str(cell).ljust(width) for cell, width in zip(line, widths)).rstrip() for line in lines)
+
+
+@connector_app.command("list")
+def connector_list(
+    hub: bool = typer.Option(False, "--hub", help="Every connector this organization can use, published ones included"),
+    query: Optional[str] = typer.Option(None, "--query", help="Filter by slug, name or description"),
+    host: Optional[str] = typer.Option(None, "--host", envvar="GATEWAY_HOST"),
+):
+    """List this organization's workspace connectors (--hub adds the ones other organizations published)."""
+    from gatewaysdk.connectors import GatewayConnectorsError
+
+    try:
+        rows = _connectors_client(host).hub(query)
+    except GatewayConnectorsError as error:
+        typer.echo(str(error), err=True)
+        raise typer.Exit(1)
+    if not hub:
+        rows = [row for row in rows if row.get("isOwn")]
+    if not rows:
+        typer.echo(
+            "no connectors" + (" in the hub" if hub else "; `gateway worlds connector publish` adds one"), err=True
+        )
+        return
+    header = ["slug", "name", "vendor", "auth", "entities", "operations", "visibility"] + (["org"] if hub else [])
+    table = []
+    for row in rows:
+        meta = row.get("metadata") if isinstance(row.get("metadata"), dict) else {}
+        line = [
+            row.get("slug", ""),
+            row.get("name", ""),
+            meta.get("vendor") or "-",
+            meta.get("auth") or "-",
+            str(meta.get("entityCount", "-")),
+            str(meta.get("operationCount", "-")),
+            row.get("visibility", ""),
+        ]
+        if hub:
+            line.append(f"{row.get('orgName', '')}{' (own)' if row.get('isOwn') else ''}")
+        table.append(line)
+    typer.echo(_table(table, header))
+
+
+@connector_app.command("pull")
+def connector_pull(
+    slug: str = typer.Argument(..., help="Workspace connector slug"),
+    out: Optional[Path] = typer.Option(None, "--out", help="New or empty directory (default: ./<slug>)"),
+    version: Optional[str] = typer.Option(None, "--version", help="A label or commit hash; the head by default"),
+    host: Optional[str] = typer.Option(None, "--host", envvar="GATEWAY_HOST"),
+):
+    """Write the connector's template files to a directory."""
+    from gatewaysdk.connectors import GatewayConnectorsError
+
+    out = out or Path(slug)
+    if out.exists() and (not out.is_dir() or any(out.iterdir())):
+        typer.echo(f"{out}: must be a new or empty directory", err=True)
+        raise typer.Exit(1)
+    try:
+        pulled = _connectors_client(host).pull(slug, version)
+    except GatewayConnectorsError as error:
+        typer.echo(str(error), err=True)
+        raise typer.Exit(1)
+    for relative, content in sorted(pulled["files"].items()):
+        if relative.startswith("/") or ".." in relative.split("/"):
+            typer.echo(f"Refusing a template path outside the directory: {relative}", err=True)
+            raise typer.Exit(1)
+        target = out / relative
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_text(content, encoding="utf-8")
+        typer.echo(relative)
+    typer.echo(f"# {slug} @ {pulled['commit'].get('commitHash') or pulled['commit'].get('id', '')} -> {out}", err=True)
+
+
+@connector_app.command("clone")
+def connector_clone(
+    source: str = typer.Argument(..., help="A hub connector's slug or repo id"),
+    name: Optional[str] = typer.Option(None, "--name", help="Name for the clone (default: the source's)"),
+    slug: Optional[str] = typer.Option(None, "--slug", help="Slug for the clone (default: the source's)"),
+    project_scope: bool = typer.Option(False, "--project-scope", help="Own it in this project rather than the org"),
+    host: Optional[str] = typer.Option(None, "--host", envvar="GATEWAY_HOST"),
+):
+    """Copy a connector another organization published into this organization, with provenance."""
+    from gatewaysdk.connectors import GatewayConnectorsError
+
+    client = _connectors_client(host)
+    try:
+        rows = client.hub()
+        by_id = [row for row in rows if row.get("id") == source]
+        if by_id:
+            chosen = by_id[0]
+        else:
+            matches = [row for row in rows if row.get("slug") == source]
+            candidates = [row for row in matches if not row.get("isOwn")] or matches
+            if not candidates:
+                typer.echo(f"{source}: not in the hub; `gateway worlds connector list --hub` shows what is", err=True)
+                raise typer.Exit(1)
+            if len(candidates) > 1:
+                typer.echo(f"{source} names {len(candidates)} hub connectors; clone by repo id instead:", err=True)
+                for row in candidates:
+                    typer.echo(f"  {row.get('id')}  {row.get('orgName')}", err=True)
+                raise typer.Exit(1)
+            chosen = candidates[0]
+        result = client.clone(chosen["id"], name=name, slug=slug, scope="project" if project_scope else "org")
+    except GatewayConnectorsError as error:
+        typer.echo(str(error), err=True)
+        raise typer.Exit(1)
+    typer.echo(
+        f"cloned {chosen.get('slug')} from {chosen.get('orgName')} -> {result.get('slug')} "
+        f"({result.get('id')}) commit {result.get('commitId')}"
+    )
+
+
+def _print_or_install_skill(name: str, install: Optional[Path], force: bool) -> None:
+    from gatewaysdk.connectors.skill import install_skill, next_step, packaged_skills, skill_text
+
+    try:
+        text = skill_text(name)
+    except KeyError:
+        typer.echo(f"No packaged skill {name!r}; the package ships: {', '.join(packaged_skills())}", err=True)
+        raise typer.Exit(1)
+    if install is None:
+        typer.echo(text, nl=False)
+        return
+    report = install_skill(install, name=name, force=force)
+    if report.conflicts:
+        typer.echo("Refusing to overwrite files that differ from the packaged skill:", err=True)
+        for relative in report.conflicts:
+            typer.echo(f"  {install / relative}", err=True)
+        typer.echo("Pass --force to replace them.", err=True)
+        raise typer.Exit(1)
+    for relative in report.written:
+        typer.echo(f"wrote {install / relative}")
+    for relative in report.unchanged:
+        typer.echo(f"unchanged {install / relative}")
+    step = next_step(name)
+    if step:
+        typer.echo(f"next: {step}")
+
+
+@connector_app.command("skill")
+def connector_skill(
+    install: Optional[Path] = typer.Option(
+        None, "--install", help="Repository to install the skill and agent into (under its .claude/)"
+    ),
+    force: bool = typer.Option(False, "--force", help="Overwrite an existing file whose content differs"),
+):
+    """The connector authoring skill for agents: print it, or --install it into a repository's .claude/.
+
+    An alias of `gateway worlds skill connector-schema-authoring`. Installed, Claude Code, Cursor and
+    Codex pick up the checklist and the connector-template-author agent; the finished template becomes
+    a workspace connector with `gateway worlds connector publish`.
+    """
+    from gatewaysdk.connectors.skill import SKILL_NAME
+
+    _print_or_install_skill(SKILL_NAME, install, force)
+
+
+@worlds_app.command("skill")
+def worlds_skill(
+    name: Optional[str] = typer.Argument(
+        None, help="Packaged skill: connector-schema-authoring, world-data-ingestion, worlds-getting-started"
+    ),
+    list_skills: bool = typer.Option(False, "--list", help="List the skills this SDK ships and exit"),
+    install: Optional[Path] = typer.Option(
+        None,
+        "--install",
+        help="Repository to install the skill (and any agent it ships) into, under .claude/; every skill when no NAME",
+    ),
+    force: bool = typer.Option(False, "--force", help="Overwrite an existing file whose content differs"),
+):
+    """Print a packaged skill for an agent, or --install it into a repository's .claude/:
+
+    gateway worlds skill --list
+    gateway worlds skill worlds-getting-started
+    gateway worlds skill world-data-ingestion --install .
+    gateway worlds skill --install .          # every packaged skill
+    """
+    from gatewaysdk.connectors.skill import packaged_skills
+
+    if list_skills or (name is None and install is None):
+        for skill in packaged_skills():
+            typer.echo(skill)
+        if name is None and not list_skills:
+            typer.echo("Name one to print it, or --install DIR to land every skill in a repository.", err=True)
+        return
+    if name is None:
+        # `--install DIR` alone: every packaged skill, so an agent needs one command.
+        for skill in packaged_skills():
+            _print_or_install_skill(skill, install, force)
+        return
+    _print_or_install_skill(name, install, force)
+
+
+data_app = typer.Typer(help="Put rows into a world, or see what it holds — local directory or platform slug")
+worlds_app.add_typer(data_app, name="data")
+
+
+def _with_world(world: str, host: Optional[str]):
+    """Yield a directory for ``world``: itself when it is one, else the platform world of that
+    slug pulled into a temporary directory (so a slug never needs a checkout to work on).
+    """
+    import contextlib
+    import tempfile as _tempfile
+
+    @contextlib.contextmanager
+    def local():
+        yield Path(world), None
+
+    @contextlib.contextmanager
+    def pulled():
+        from gatewaysdk.benchmark_hub import GatewayBenchmarkClient
+
+        client = GatewayBenchmarkClient.from_env(host)
+        with _tempfile.TemporaryDirectory(prefix="gateway-world-data-") as directory:
+            slug = world.split("@", 1)[0]
+            pulled_dir = Path(directory) / slug
+            client.pull(world, target=str(pulled_dir))
+            yield pulled_dir, client
+
+    return local() if Path(world).is_dir() else pulled()
+
+
+def _is_directory(world: str) -> bool:
+    return Path(world).is_dir()
+
+
+def _world_slug(root: Path) -> str:
+    """The platform slug a local world would import into: its pulled metadata, else its name."""
+    meta = root / ".gateway" / ".env-metadata.json"
+    if meta.is_file():
+        try:
+            slug = json.loads(meta.read_text(encoding="utf-8")).get("slug")
+            if isinstance(slug, str) and slug:
+                return slug
+        except (OSError, ValueError):
+            pass
+    return root.resolve().name
+
+
+def _data_client(host: Optional[str]):
+    from gatewaysdk.world_data import WorldDataClient
+
+    return WorldDataClient.from_env(host)
+
+
+def _local_check(
+    root: Path, rows: List[Path], entity: Optional[str], mode: str, merge: str, atomic: bool
+) -> Dict[str, Any]:
+    """Validate rows files against a world directory's contract in a scratch snapshot:
+    the shape of every row, then references and keys at apply time. Applies nothing."""
+    import shutil as _shutil
+    import tempfile as _tempfile
+
+    from gatewaysdk.environment.schema.batch import ChunkSpec, build_batch, chunk_rows, iter_rows
+    from gatewaysdk.environment.schema.compiler import check_bundle
+    from gatewaysdk.environment.schema.snapshot import EMPTY_DIGEST, build_default, default_snapshot
+
+    contract = check_bundle(root)
+    with _tempfile.TemporaryDirectory(prefix="gateway-check-") as scratch:
+        work = Path(scratch)
+        chunks = list(chunk_rows(iter_rows([str(r) for r in rows], entity=entity), work / "chunks", entity=entity))
+        if not chunks:
+            return {"rows": 0, "refusals": [], "refusalCount": 0, "entityCounts": {}}
+        build_default(root, contract)
+        parent = work / "state.sqlite"
+        _shutil.copyfile(default_snapshot(root), parent)
+        result = build_batch(
+            contract,
+            parent,
+            [ChunkSpec(chunk.ordinal, chunk.path, chunk.entity) for chunk in chunks],
+            mode=mode,
+            merge=merge,
+            atomic=atomic,
+            batch_id="check",
+            parent_digest=EMPTY_DIGEST,
+            dry_run=True,
+        )
+        return {
+            "rows": sum(chunk.rows for chunk in chunks),
+            "refusals": result["refusals"],
+            "refusalCount": result["refusalCount"],
+            "entityCounts": result["entityCounts"],
+        }
+
+
+def _write_refusal_report(records: List[Dict[str, Any]], destination: Path) -> None:
+    from gatewaysdk.environment.schema.batch import write_report
+
+    with open(destination, "w", encoding="utf-8") as out:
+        write_report(records, out)
+
+
+def _pulled_world(world: str, host: Optional[str]):
+    """A platform world's tree pulled into a temp dir (its contract is what a local
+    check needs); the context yields the directory."""
+    import contextlib
+    import tempfile as _tempfile
+
+    @contextlib.contextmanager
+    def pulled():
+        from gatewaysdk.benchmark_hub import GatewayBenchmarkClient
+
+        client = GatewayBenchmarkClient.from_env(host)
+        with _tempfile.TemporaryDirectory(prefix="gateway-world-data-") as directory:
+            pulled_dir = Path(directory) / world.split("@", 1)[0]
+            client.pull(world, target=str(pulled_dir))
+            yield pulled_dir
+
+    return pulled()
+
+
+@data_app.command("import")
+def data_import(
+    world: str = typer.Argument(..., help="World directory, or a platform world slug (optionally slug@ref)."),
+    rows: List[str] = typer.Argument(
+        ..., help="Rows files ({entity: [rows]} JSON, {entity,row} JSONL, bare rows), or - for stdin."
+    ),
+    entity: Optional[str] = typer.Option(None, "--entity", help="The entity bare-row files hold."),
+    mode: str = typer.Option("append", "--mode", help="append (upsert by primary key) | replace (named entities)."),
+    merge: str = typer.Option(
+        "upsert", "--merge", help="Inside the batch, by key: upsert (last wins) | fill (first wins, later add fields)."
+    ),
+    chunk_rows: Optional[int] = typer.Option(
+        None, "--chunk-rows", help="Rows per uploaded chunk (instead of --chunk-bytes)."
+    ),
+    chunk_bytes: Optional[str] = typer.Option(
+        None, "--chunk-bytes", help="JSONL bytes per uploaded chunk before gzip (default 64MiB)."
+    ),
+    parallel: int = typer.Option(4, "--parallel", help="Chunk uploads in flight."),
+    resume: bool = typer.Option(
+        False, "--resume", help="Pick up the newest incomplete upload of this world and these files."
+    ),
+    atomic: bool = typer.Option(
+        True, "--atomic/--per-chunk", help="One refusal refuses the batch (atomic) or only its chunk."
+    ),
+    publish: str = typer.Option("now", "--publish", help="now: a version per batch | later: fold with `data publish`."),
+    wait_: bool = typer.Option(
+        True, "--wait/--no-wait", help="Wait for the batch to apply (or print {batchId, state})."
+    ),
+    report: Optional[Path] = typer.Option(None, "--report", help="Write the refusals as JSONL here."),
+    dry_run: bool = typer.Option(
+        False, "--dry-run", help="Validate locally against the contract; upload and write nothing."
+    ),
+    message: Optional[str] = typer.Option(None, "--message", "-m", help="Change reason for the version."),
+    host: Optional[str] = typer.Option(None, "--host", envvar="GATEWAY_HOST"),
+) -> None:
+    """Put rows into a world through its own gate:
+
+        gateway worlds data import ./acme-world customers.json --mode append
+        gateway worlds data import acme-world export.jsonl --entity customers --chunk-bytes 64MiB -m "Q3 customers"
+
+    A directory: the rows go into the tree (data/initial.json for a schema world, db/seed.sql for
+    mock-tools), small inputs only. A slug: the rows stream up as gzipped chunks into a data batch
+    the platform validates, applies onto the world's snapshot and (with --publish now) turns into a
+    data-only version. Exit 0 applied or published, 2 refused (report written), 1 error.
+    """
+    from gatewaysdk.environment.errors import WorldStartError
+    from gatewaysdk.environment.schema import ContractError
+    from gatewaysdk.environment.schema.data import INLINE_BYTES, INLINE_ROWS, MERGES, MODES, import_rows, parse_rows
+    from gatewaysdk.world_data import Flags, WorldDataError, tty_progress
+
+    if mode not in MODES or merge not in MERGES or publish not in ("now", "later"):
+        typer.echo("--mode is append|replace, --merge is upsert|fill, --publish is now|later", err=True)
+        raise typer.Exit(1)
+    try:
+        size = _parse_size(chunk_bytes) if chunk_bytes else None
+        if _is_directory(world) or dry_run:
+            root_ctx = _local_root(world, host)
+            with root_ctx as root:
+                if dry_run:
+                    checked = _local_check(root, [Path(r) for r in rows], entity, mode, merge, atomic)
+                    if report is not None:
+                        _write_refusal_report(checked["refusals"], report)
+                    typer.echo(json.dumps({"world": world, "dryRun": True, **_summary(checked)}, indent=2))
+                    raise typer.Exit(2 if checked["refusalCount"] else 0)
+                _refuse_large_local(root, [Path(r) for r in rows], entity, INLINE_ROWS, INLINE_BYTES)
+                parsed = parse_rows([Path(r) for r in rows], entity=entity)
+                result = import_rows(root, parsed, mode=mode)
+                typer.echo(json.dumps({"world": world, **result}, indent=2))
+                return
+        client = _data_client(host)
+        progress = tty_progress()
+        from gatewaysdk.world_data import import_rows as upload_rows
+        from gatewaysdk.world_data import wait as wait_batch
+        from gatewaysdk.world_data import write_status_report
+
+        flags = Flags(
+            mode=mode,
+            merge=merge,
+            atomic=atomic,
+            publish=publish,
+            dryRun=False,
+            chunkBytes=size or Flags().chunkBytes,
+            chunkRows=chunk_rows,
+            entity=entity,
+        )
+        manifest = upload_rows(
+            client, world, list(rows), flags=flags, parallel=parallel, resume=resume, message=message, progress=progress
+        )
+        if not wait_:
+            typer.echo(json.dumps({"batchId": manifest.batch_id, "state": "queued"}))
+            return
+        status = wait_batch(client, world, manifest.batch_id, progress=progress)
+        if report is not None:
+            write_status_report(client, status, report)
+        typer.echo(json.dumps({"world": world, **status}, indent=2))
+        state = status.get("state")
+        raise typer.Exit(0 if state in ("applied", "published") else 2 if state == "refused" else 1)
+    except (ContractError, WorldStartError, WorldDataError, OSError, ValueError) as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(1)
+
+
+def _local_root(world: str, host: Optional[str]):
+    import contextlib
+
+    @contextlib.contextmanager
+    def local():
+        yield Path(world)
+
+    return local() if _is_directory(world) else _pulled_world(world, host)
+
+
+def _parse_size(text: str) -> int:
+    units = {
+        "": 1,
+        "b": 1,
+        "k": 1024,
+        "kib": 1024,
+        "kb": 1000,
+        "m": 1024**2,
+        "mib": 1024**2,
+        "mb": 1000**2,
+        "g": 1024**3,
+        "gib": 1024**3,
+        "gb": 1000**3,
+    }
+    raw = text.strip().lower().replace(" ", "")
+    digits = raw.rstrip("abcdefghijklmnopqrstuvwxyz")
+    unit = raw[len(digits) :]
+    if not digits.isdigit() or unit not in units:
+        raise ValueError(f"--chunk-bytes takes a size like 64MiB or 1000000, not {text!r}")
+    return int(digits) * units[unit]
+
+
+def _summary(checked: Dict[str, Any]) -> Dict[str, Any]:
+    return {
+        "rows": checked["rows"],
+        "refusalCount": checked["refusalCount"],
+        "refusals": checked["refusals"][:200],
+        "entityCounts": checked["entityCounts"],
+    }
+
+
+def _refuse_large_local(root: Path, rows: List[Path], entity: Optional[str], max_rows: int, max_bytes: int) -> None:
+    from gatewaysdk.environment.schema.batch import count_rows
+
+    size = sum(path.stat().st_size for path in rows if str(path) != "-" and path.is_file())
+    if size > max_bytes or count_rows([str(r) for r in rows], entity=entity, cap=max_rows) > max_rows:
+        raise ValueError(
+            f"{len(rows)} file(s) exceed the inline cap ({max_rows} rows / {max_bytes} bytes) for a directory; "
+            f"import into the platform world `{_world_slug(root)}`"
+        )
+
+
+@data_app.command("check")
+def data_check(
+    world: str = typer.Argument(..., help="World directory, or a platform world slug (its contract is pulled)."),
+    rows: List[str] = typer.Argument(..., help="Rows files, or - for stdin."),
+    entity: Optional[str] = typer.Option(None, "--entity", help="The entity bare-row files hold."),
+    mode: str = typer.Option("append", "--mode", help="append | replace, as the import would run."),
+    merge: str = typer.Option("upsert", "--merge", help="upsert | fill, as the import would run."),
+    report: Optional[Path] = typer.Option(None, "--report", help="Write the refusals as JSONL here."),
+    host: Optional[str] = typer.Option(None, "--host", envvar="GATEWAY_HOST"),
+) -> None:
+    """Dry run: every row checked against the world's contract (shape, keys, references) in a
+    scratch snapshot; nothing uploaded, nothing written. Exit 2 when any row is refused.
+
+        gateway worlds data check acme-world export.jsonl --report refusals.jsonl
+    """
+    from gatewaysdk.environment.schema import ContractError
+    from gatewaysdk.world_data import WorldDataError
+
+    try:
+        with _local_root(world, host) as root:
+            checked = _local_check(root, [Path(r) for r in rows], entity, mode, merge, True)
+    except (ContractError, WorldDataError, OSError, ValueError) as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(1)
+    if report is not None:
+        _write_refusal_report(checked["refusals"], report)
+    typer.echo(json.dumps({"world": world, "dryRun": True, **_summary(checked)}, indent=2))
+    raise typer.Exit(2 if checked["refusalCount"] else 0)
+
+
+@data_app.command("extract")
+def data_extract(
+    world: str = typer.Argument(..., help="World directory, or a platform world slug (its contract is pulled)."),
+    source: str = typer.Argument(..., help="Input file, or - for stdin."),
+    shape: str = typer.Option(..., "--shape", help="tool-results | vendor-envelope | session-export."),
+    entity: str = typer.Option(..., "--entity", help="The entity the rows belong to."),
+    out: Optional[str] = typer.Option(None, "--out", help="Write tagged JSONL here (default stdout, also -)."),
+    merge: str = typer.Option("fill", "--merge", help="Dedupe by primary key: fill (first wins) | upsert (last wins)."),
+    no_redact: bool = typer.Option(False, "--no-redact", help="Skip the world's [redact] policy."),
+    host: Optional[str] = typer.Option(None, "--host", envvar="GATEWAY_HOST"),
+) -> None:
+    """Rows out of a tool-results export, a vendor response or a session export, shaped for
+    `data import`: null and empty fields dropped, undeclared fields stripped (and counted on
+    stderr), deduped by primary key, the world's [redact] policy applied.
+
+        gateway worlds data extract ./spycloud-world calls.jsonl --shape session-export --entity records --out rows.jsonl
+    """
+    import contextlib
+
+    from gatewaysdk.environment.schema import ContractError
+    from gatewaysdk.environment.schema.extract import extract
+    from gatewaysdk.world_data import WorldDataError
+
+    try:
+        with _local_root(world, host) as root:
+            sink = contextlib.nullcontext(sys.stdout) if out in (None, "-") else open(out, "w", encoding="utf-8")
+            with sink as stream:
+                summary = extract(
+                    root, [source], shape=shape, entity=entity, merge=merge, redaction=not no_redact, out=stream
+                )
+    except (ContractError, WorldDataError, OSError, ValueError) as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(1)
+    typer.echo(json.dumps(summary.to_json()), err=True)
+
+
+@data_app.command("status")
+def data_status(
+    batch_id: str = typer.Argument(..., help="The batch id `data import` printed or recorded in .gateway/imports/."),
+    world: Optional[str] = typer.Option(None, "--world", help="The world slug, when no manifest names it."),
+    host: Optional[str] = typer.Option(None, "--host", envvar="GATEWAY_HOST"),
+) -> None:
+    """One batch's state, progress, counts and first refusals."""
+    from gatewaysdk.world_data import MANIFEST_DIR, Manifest, WorldDataError
+
+    slug = world
+    if slug is None:
+        manifest_path = Path.cwd() / MANIFEST_DIR / f"{batch_id}.json"
+        if manifest_path.is_file():
+            slug = Manifest.load(manifest_path).data.get("slug")
+    if not slug:
+        typer.echo(f"no manifest for {batch_id} under {MANIFEST_DIR}; pass --world SLUG", err=True)
+        raise typer.Exit(1)
+    try:
+        typer.echo(json.dumps(_data_client(host).status(slug, batch_id), indent=2))
+    except (WorldDataError, ValueError) as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(1)
+
+
+@data_app.command("batches")
+def data_batches(
+    world: str = typer.Argument(..., help="World slug."),
+    limit: Optional[int] = typer.Option(None, "--limit", help="At most this many, newest first."),
+    host: Optional[str] = typer.Option(None, "--host", envvar="GATEWAY_HOST"),
+) -> None:
+    """The world's data batches, newest first."""
+    from gatewaysdk.world_data import WorldDataError
+
+    try:
+        typer.echo(json.dumps(_data_client(host).batches(world, limit=limit), indent=2))
+    except (WorldDataError, ValueError) as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(1)
+
+
+@data_app.command("publish")
+def data_publish(
+    world: str = typer.Argument(..., help="World slug."),
+    message: Optional[str] = typer.Option(None, "--message", "-m", help="Change reason for the version."),
+    host: Optional[str] = typer.Option(None, "--host", envvar="GATEWAY_HOST"),
+) -> None:
+    """Fold every applied `--publish later` batch into one data-only version."""
+    from gatewaysdk.world_data import WorldDataError
+
+    try:
+        typer.echo(json.dumps(_data_client(host).publish(world, message), indent=2))
+    except (WorldDataError, ValueError) as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(1)
+
+
+@data_app.command("show")
+def data_show(
+    world: str = typer.Argument(..., help="World directory, or a platform world slug (optionally slug@ref)."),
+    entity: Optional[str] = typer.Option(None, "--entity", help="Print this entity's rows instead of counts."),
+    host: Optional[str] = typer.Option(None, "--host", envvar="GATEWAY_HOST"),
+) -> None:
+    """What a world seeds with: every entity's row count, or one entity's rows:
+
+    gateway worlds data show ./acme-world
+    gateway worlds data show acme-world --entity customers
+
+    A directory answers from its compiled snapshot when it has one; a slug asks the platform,
+    which reads the world's snapshot.
+    """
+    from gatewaysdk.environment.errors import WorldStartError
+    from gatewaysdk.environment.schema import ContractError
+    from gatewaysdk.environment.schema.data import entity_counts, entity_rows, world_kind
+    from gatewaysdk.world_data import WorldDataError
+
+    try:
+        if not _is_directory(world):
+            answer = _data_client(host).counts(world, entity)
+            out: Dict[str, Any] = {
+                "world": world,
+                "kind": answer.get("kind"),
+                "entity_counts": answer.get("entityCounts"),
+            }
+            if entity is not None:
+                out["entity"] = entity
+                out["rows"] = answer.get("rows")
+            typer.echo(json.dumps(out, indent=2))
+            return
+        root = Path(world)
+        out = {"world": world, "kind": world_kind(root)}
+        if entity is None:
+            out["entity_counts"] = entity_counts(root)
+        else:
+            out["entity"] = entity
+            out["rows"] = entity_rows(root, entity)
+    except (ContractError, WorldStartError, WorldDataError, OSError, ValueError) as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(1)
+    typer.echo(json.dumps(out, indent=2))
+
+
+@worlds_app.command("serve")
+def worlds_serve(
+    path: Path = typer.Argument(..., help="World directory holding connector.toml"),
+    port: int = typer.Option(8080, help="Port to listen on"),
+    api_key: Optional[str] = typer.Option(
+        None, "--api-key", help="Require this credential; default accepts any non-empty one"
+    ),
+    scenario: Optional[str] = typer.Option(None, "--scenario", help="Start in one of the world's scenarios/<name>"),
+):
+    """Serve the world's vendor API locally: its routes answered from its store, no platform needed."""
+    from gatewaysdk.environment.schema.api import serve_forever
+
+    serve_forever(path, port=port, api_key=api_key, scenario=scenario)
+
+
+@schema_app.command("api-bundle")
+def schema_api_bundle(
+    path: Path = typer.Argument(..., help="World directory holding connector.toml"),
+    out: Path = typer.Option(..., "--out", help="Empty directory for the api-kind bundle"),
+):
+    """Write the api-kind bundle the platform hosts for this world. `gateway bench push` does this for you."""
+    from gatewaysdk.environment.schema.api import build_api_bundle
+
+    typer.echo(f"api bundle: {build_api_bundle(path, out)}")
+
+
+def _read_task_spec(file: Path, flag: str = "--spec") -> Dict[str, Any]:
+    """A task spec from a JSON file: ``{instruction, seed?, grader?, metadata?, name?}``."""
+    try:
+        parsed = json.loads(file.read_text(encoding="utf-8"))
+    except (OSError, ValueError) as exc:
+        typer.echo(f"{flag} {file}: {exc}", err=True)
+        raise typer.Exit(2)
+    if not isinstance(parsed, dict) or not isinstance(parsed.get("instruction"), str):
+        typer.echo(f'{flag} {file}: a task spec is a JSON object with an "instruction" string', err=True)
+        raise typer.Exit(2)
+    return parsed
+
+
+def _task_from_flags(
+    task: Optional[str],
+    task_id: Optional[str],
+    task_version: Optional[int],
+    task_file: Optional[Path],
+) -> Any:
+    """Exactly one task source: a bundled name (``--task``), a stored task
+    (``--task-id``, optionally ``--task-version``) or an inline spec read from
+    a JSON file (``--task-file``). Same refusals as the TS CLI."""
+    if sum(1 for given in (task, task_id, task_file) if given) > 1:
+        typer.echo("worlds session open takes one of --task, --task-id or --task-file", err=True)
+        raise typer.Exit(2)
+    if task_version is not None and not task_id:
+        typer.echo("--task-version needs --task-id", err=True)
+        raise typer.Exit(2)
+    if task:
+        return task
+    if task_id:
+        return {"id": task_id} if task_version is None else {"id": task_id, "version": task_version}
+    if task_file is None:
+        typer.echo("worlds session open needs --task, --task-id or --task-file", err=True)
+        raise typer.Exit(2)
+    return _read_task_spec(task_file, "--task-file")
+
+
+def _task_json(session: Any) -> Dict[str, Any]:
+    task = session.task_info
+    out: Dict[str, Any] = {"source": task.source, "name": task.name, "hash": task.hash, "metadata": task.metadata}
+    if task.source == "stored":
+        out["id"] = task.id
+        out["version"] = task.version
+    return out
+
+
+def _world_from_flags(world: Optional[str], no_world: bool) -> Any:
+    """``--world <slug>`` / ``--no-world`` → the API's ``world``: slug, ``None``
+    to unpin, or the ``_UNSET`` marker when neither was given."""
+    from gatewaysdk.world_sessions import _UNSET
+
+    if world and no_world:
+        typer.echo("--world and --no-world exclude each other", err=True)
+        raise typer.Exit(2)
+    if no_world:
+        return None
+    return world if world else _UNSET
+
+
+def _camel_keys(value: Any) -> Any:
+    """``asdict`` output with snake_case field names back in the wire's camelCase.
+    Only dataclass fields are renamed; a ``spec`` (customer JSON) is left alone."""
+
+    def camel(name: str) -> str:
+        head, *rest = name.split("_")
+        return head + "".join(part.title() for part in rest)
+
+    if isinstance(value, list):
+        return [_camel_keys(item) for item in value]
+    if isinstance(value, dict):
+        return {camel(key): (value[key] if key == "spec" else _camel_keys(value[key])) for key in value}
+    return value
+
+
+def _task_result_json(result: Any) -> Dict[str, Any]:
+    """A ``world_tasks`` dataclass as the platform's JSON."""
+    return _camel_keys(asdict(result))
+
+
+def _surfaces_json(session: Any) -> Dict[str, Any]:
+    s = session.surfaces
+    out: Dict[str, Any] = {"sessionId": session.session_id, "surfaces": s.kinds}
+    if s.api is not None:
+        out["api"] = {"url": s.api.url}
+        if s.api.token:
+            out["api"]["token"] = s.api.token
+    if s.ui is not None:
+        out["ui"] = {"url": s.ui.url, "entry": s.ui.entry_url, "apiPath": s.ui.api_path}
+    if s.browser is not None:
+        out["browser"] = {"wsUrl": s.browser.ws_url, "viewport": s.browser.viewport}
+    return out
+
+
+@session_app.command("open")
+def session_open(
+    slug: str = typer.Argument(..., help="World slug (optionally slug@ref)."),
+    task: Optional[str] = typer.Option(None, "--task", "-t", help="Bundled task / scenario to open the session on."),
+    task_id: Optional[str] = typer.Option(
+        None, "--task-id", help="Stored task (see `worlds task`) to open the session on instead of --task."
+    ),
+    task_version: Optional[int] = typer.Option(
+        None, "--task-version", help="With --task-id: open that version of the task instead of the current one."
+    ),
+    task_file: Optional[Path] = typer.Option(
+        None,
+        "--task-file",
+        help="JSON file holding an inline task spec {instruction, seed?, grader?, metadata?} (World Host worlds).",
+    ),
+    surface: List[str] = typer.Option(
+        [],
+        "--surface",
+        "-s",
+        help="Surface to ask for besides tools: api, ui, browser (repeatable).",
+    ),
+    version_id: Optional[str] = typer.Option(None, "--version-id", help="Pin an exact world version."),
+    no_wait: bool = typer.Option(False, "--no-wait", help="Return as soon as the platform accepts the session."),
+    host: Optional[str] = typer.Option(None, "--host", envvar="GATEWAY_HOST"),
+) -> None:
+    """Open a live session and print where it answers:
+
+        gateway worlds session open payments-like -t refund-double-charge \\
+            -s api -s ui -s browser
+
+    ``--task-file task.json`` opens on an inline task instead of a bundled
+    one: ``{instruction, seed?, grader?, metadata?}``, the session's own.
+    ``--task-id <id>`` opens a copy of a stored task's current (or
+    ``--task-version``) spec.
+
+    Prints ``{sessionId, ready, surfaces, api.url, ui.entry, browser.wsUrl,
+    task}`` — the same descriptor ``WorldSession.surfaces`` parses, plus the
+    platform's task block (source bundled|stored|inline, name, hash, id/version). The
+    platform refuses (HTTP 400) rather than serving fewer surfaces than asked.
+    """
+    from gatewaysdk.world_sessions import WorldSessionError, WorldSessionTimeout, open_session
+
+    task_ref = _task_from_flags(task, task_id, task_version, task_file)
+    try:
+        session = open_session(slug, task_ref, version_id=version_id, surfaces=surface or None, host=host)
+    except (WorldSessionError, ValueError) as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(1)
+
+    def descriptor(ready: bool) -> Dict[str, Any]:
+        return {**_surfaces_json(session), "ready": ready, "task": _task_json(session)}
+
+    if not no_wait:
+        try:
+            session.ready()
+        except WorldSessionTimeout as exc:
+            # The session is still coming (a cold pod takes longer than this
+            # wait): print where it will answer so the caller polls instead of
+            # losing the id and opening another one.
+            typer.echo(json.dumps(descriptor(False), indent=2))
+            typer.echo(
+                f"{exc} Poll `gateway worlds session status {session.session_id}` until ready.",
+                err=True,
+            )
+            raise typer.Exit(1)
+        except WorldSessionError as exc:
+            typer.echo(str(exc), err=True)
+            raise typer.Exit(1)
+    typer.echo(json.dumps(descriptor(session.is_ready), indent=2))
+
+
+@session_app.command("status")
+def session_status(
+    session_id: str = typer.Argument(...),
+    host: Optional[str] = typer.Option(None, "--host", envvar="GATEWAY_HOST"),
+) -> None:
+    """Print a session's state, tools and surfaces."""
+    from gatewaysdk.world_sessions import WorldSessionError, attach_session
+
+    try:
+        session = attach_session(session_id, host=host)
+        out = dict(session.status())
+        out.update(_surfaces_json(session))
+        typer.echo(json.dumps(out, indent=2))
+    except WorldSessionError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(1)
+
+
+@session_app.command("state")
+def session_state(
+    session_id: str = typer.Argument(...),
+    host: Optional[str] = typer.Option(None, "--host", envvar="GATEWAY_HOST"),
+) -> None:
+    """Dump the world's state right now — every entity's rows, what a grader reads."""
+    from gatewaysdk.world_sessions import WorldSessionError, attach_session
+
+    try:
+        typer.echo(json.dumps(attach_session(session_id, host=host).state(), indent=2))
+    except WorldSessionError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(1)
+
+
+@session_app.command("reset")
+def session_reset(
+    session_id: str = typer.Argument(...),
+    host: Optional[str] = typer.Option(None, "--host", envvar="GATEWAY_HOST"),
+) -> None:
+    """Put the world back to its opening state (snapshot plus the task's seed)."""
+    from gatewaysdk.world_sessions import WorldSessionError, attach_session
+
+    try:
+        attach_session(session_id, host=host).reset()
+    except WorldSessionError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(1)
+    typer.echo(json.dumps({"sessionId": session_id, "reset": True}, indent=2))
+
+
+@session_app.command("grade")
+def session_grade(
+    session_id: str = typer.Argument(...),
+    timeout: Optional[float] = typer.Option(
+        None,
+        "--timeout",
+        help="Seconds to wait for the grade; defaults to the grader's budget (a rubric judge gets 15 min).",
+    ),
+    host: Optional[str] = typer.Option(None, "--host", envvar="GATEWAY_HOST"),
+) -> None:
+    """Run the session's task grader against the world's current state and print {reward, rewards, raw}.
+
+    Assertions and python graders answer from the engine in seconds. A rubric grader is
+    judged by the platform's worker; the command waits for that verdict.
+    """
+    from gatewaysdk.world_sessions import (
+        WorldSessionError,
+        attach_session,
+        named_rewards,
+    )
+
+    if timeout is not None and timeout <= 0:
+        typer.echo("--timeout must be a positive number of seconds", err=True)
+        raise typer.Exit(1)
+    try:
+        raw = attach_session(session_id, host=host).grade(timeout=timeout)
+    except WorldSessionError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(1)
+    reward = raw.get("reward")
+    out = {
+        "sessionId": session_id,
+        "reward": reward if isinstance(reward, (int, float)) and not isinstance(reward, bool) else None,
+        "rewards": named_rewards(raw),
+        "raw": raw,
+    }
+    typer.echo(json.dumps(out, indent=2))
+
+
+@session_app.command("browse")
+def session_browse(
+    session_id: str = typer.Argument(...),
+    mode: str = typer.Option("auto", "--mode", help="hosted | local | auto (prefers hosted)."),
+    path: Optional[str] = typer.Option(None, "--path", help="UI path to open instead of the declared entry."),
+    screenshot: Optional[str] = typer.Option(None, "--screenshot", help="Write a PNG of the page here."),
+    host: Optional[str] = typer.Option(None, "--host", envvar="GATEWAY_HOST"),
+) -> None:
+    """Open the session's UI in its browser surface and print what the agent
+    would read — a smoke test for the ui/browser surfaces:
+
+        gateway worlds session browse ws_123 --path /customers --screenshot out.png
+    """
+    from gatewaysdk.world_sessions import WorldSessionError, attach_session
+
+    try:
+        session = attach_session(session_id, host=host)
+        with session.browser(mode=mode) as browser:
+            url = browser.goto(path) if path else browser.goto()
+            if screenshot:
+                Path(screenshot).write_bytes(browser.screenshot())
+            typer.echo(json.dumps({"url": url, "title": browser.title(), "text": browser.text()}, indent=2))
+    except WorldSessionError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(1)
+
+
+@session_app.command("close")
+def session_close(
+    session_id: str = typer.Argument(...),
+    keep_warm: bool = typer.Option(False, "--keep-warm", help="Hand the container back to the warm pool."),
+    host: Optional[str] = typer.Option(None, "--host", envvar="GATEWAY_HOST"),
+) -> None:
+    """End a session."""
+    from gatewaysdk.world_sessions import WorldSessionError, attach_session
+
+    try:
+        typer.echo(json.dumps(attach_session(session_id, host=host).close(keep_warm=keep_warm), indent=2))
+    except WorldSessionError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(1)
+
+
+@session_app.command("seed")
+def session_seed(
+    session_id: str = typer.Argument(...),
+    rows: List[Path] = typer.Argument(..., help="Rows files: {entity: [rows]} JSON, {entity,row} JSONL, or bare rows."),
+    entity: Optional[str] = typer.Option(None, "--entity", help="The entity bare-row files hold."),
+    mode: str = typer.Option("append", "--mode", help="append (upsert by primary key) | replace (named entities)."),
+    host: Optional[str] = typer.Option(None, "--host", envvar="GATEWAY_HOST"),
+) -> None:
+    """Put rows into a LIVE session's world and wait for the engine's answer:
+
+        gateway worlds session seed ws_123 customers.json --mode replace
+
+    Posts ``{kind: "seed", args: {mode, rows}}``; the engine applies the rows through the
+    world's contract, so a refused row leaves the session unchanged and the error names it.
+    """
+    from gatewaysdk.environment.schema import ContractError
+    from gatewaysdk.environment.schema.data import parse_rows
+    from gatewaysdk.world_sessions import WorldSessionError, attach_session
+
+    try:
+        parsed = parse_rows(rows, entity=entity)
+        result = attach_session(session_id, host=host).seed(parsed, mode=mode)
+    except (ContractError, WorldSessionError, ValueError, OSError) as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(1)
+    typer.echo(json.dumps({"sessionId": session_id, "mode": mode, "result": result}, indent=2))
+
+
+@session_app.command("export")
+def session_export(
+    session_id: str = typer.Argument(...),
+    out: Optional[Path] = typer.Option(None, "--out", help="Write the JSONL here instead of stdout."),
+    host: Optional[str] = typer.Option(None, "--host", envvar="GATEWAY_HOST"),
+) -> None:
+    """The session's call log as JSONL, one ``{seq, kind, tool, args, result, error, completedAt}`` per
+    line, oldest first — turn a real run into rows for `gateway worlds data import`:
+
+        gateway worlds session export ws_123 --out run.jsonl
+    """
+    from gatewaysdk.world_sessions import WorldSessionError, attach_session
+
+    try:
+        calls = attach_session(session_id, host=host).calls()
+    except WorldSessionError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(1)
+    keys = ("seq", "kind", "tool", "args", "result", "error", "completedAt")
+    lines = [json.dumps({key: call.get(key) for key in keys}, sort_keys=True) for call in calls]
+    text = "\n".join(lines) + ("\n" if lines else "")
+    if out is None:
+        typer.echo(text, nl=False)
+        return
+    out.write_text(text, encoding="utf-8")
+    typer.echo(f"wrote {len(lines)} calls to {out}")
+
+
+session_task_app = typer.Typer(help="A session's task: promote an inline one into a stored task.", no_args_is_help=True)
+session_app.add_typer(session_task_app, name="task")
+
+
+@session_task_app.command("save")
+def session_task_save(
+    session_id: str = typer.Argument(...),
+    name: Optional[str] = typer.Option(None, "--name", "-n", help="Stored task name (default: the spec's own)."),
+    world: Optional[str] = typer.Option(None, "--world", "-w", help="Pin the task to this world slug."),
+    no_world: bool = typer.Option(False, "--no-world", help="Do not pin the task to the session's world."),
+    message: Optional[str] = typer.Option(None, "--message", "-m", help="Version note."),
+    host: Optional[str] = typer.Option(None, "--host", envvar="GATEWAY_HOST"),
+) -> None:
+    """Store the session's inline task as a reusable project task (version 1):
+
+        gateway worlds session task save ws_123 -n refund-late-invoice
+
+    The session itself keeps running unchanged; later sessions open the
+    stored copy with ``session open <world> --task-id <id>``.
+    """
+    from gatewaysdk.world_sessions import WorldSessionError, attach_session
+
+    pin = _world_from_flags(world, no_world)
+    try:
+        saved = attach_session(session_id, host=host).save_task(name=name, world=pin, message=message)
+    except WorldSessionError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(1)
+    typer.echo(json.dumps(_task_result_json(saved), indent=2))
+
+
+task_app = typer.Typer(
+    help="Stored world tasks: task specs kept by the project outside any bundle, versioned, opened by id.",
+    no_args_is_help=True,
+)
+worlds_app.add_typer(task_app, name="task")
+
+
+@task_app.command("create")
+def task_create(
+    spec: Path = typer.Argument(..., help="JSON file: {instruction, seed?, grader?, metadata?, name?}."),
+    name: Optional[str] = typer.Option(None, "--name", "-n", help="Task name (default: the spec's name)."),
+    world: Optional[str] = typer.Option(None, "--world", "-w", help="Pin the task to this world slug."),
+    message: Optional[str] = typer.Option(None, "--message", "-m", help="Version note."),
+    host: Optional[str] = typer.Option(None, "--host", envvar="GATEWAY_HOST"),
+) -> None:
+    """Store a task spec as version 1 of a new project task:
+
+    gateway worlds task create task.json -n refund-late-invoice -w acme-billing
+    """
+    from gatewaysdk.world_sessions import WorldSessionError
+    from gatewaysdk.world_tasks import create_task
+
+    parsed = _read_task_spec(spec, "spec")
+    try:
+        created = create_task(parsed, name=name, world=world, message=message, host=host)
+    except WorldSessionError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(1)
+    typer.echo(json.dumps(_task_result_json(created), indent=2))
+
+
+@task_app.command("update")
+def task_update(
+    task_id: str = typer.Argument(...),
+    spec: Optional[Path] = typer.Option(None, "--spec", help="JSON file with the new spec → the next version."),
+    name: Optional[str] = typer.Option(None, "--name", "-n", help="Rename the task."),
+    world: Optional[str] = typer.Option(None, "--world", "-w", help="Pin the task to this world slug."),
+    no_world: bool = typer.Option(False, "--no-world", help="Unpin the task from its world."),
+    message: Optional[str] = typer.Option(None, "--message", "-m", help="Version note."),
+    host: Optional[str] = typer.Option(None, "--host", envvar="GATEWAY_HOST"),
+) -> None:
+    """Change a task. A new ``--spec`` appends a version (old ones stay openable
+    with ``--task-version``); ``--name`` / ``--world`` / ``--no-world`` change in place."""
+    from gatewaysdk.world_sessions import WorldSessionError
+    from gatewaysdk.world_tasks import update_task
+
+    pin = _world_from_flags(world, no_world)
+    if spec is None and name is None and no_world is False and world is None:
+        typer.echo("worlds task update needs --spec, --name, --world or --no-world", err=True)
+        raise typer.Exit(2)
+    parsed = _read_task_spec(spec) if spec is not None else None
+    try:
+        updated = update_task(task_id, spec=parsed, name=name, world=pin, message=message, host=host)
+    except WorldSessionError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(1)
+    typer.echo(json.dumps(_task_result_json(updated), indent=2))
+
+
+@task_app.command("list")
+def task_list(
+    world: Optional[str] = typer.Option(None, "--world", "-w", help="Only tasks pinned to this world."),
+    metadata: List[str] = typer.Option(
+        [], "--metadata", help="key=value the task's spec metadata must carry (repeatable, all must match)."
+    ),
+    page: Optional[int] = typer.Option(None, "--page"),
+    limit: Optional[int] = typer.Option(None, "--limit"),
+    host: Optional[str] = typer.Option(None, "--host", envvar="GATEWAY_HOST"),
+) -> None:
+    """The project's stored tasks, newest change first:
+
+    gateway worlds task list -w acme-billing --metadata externalUserId=u_42
+    """
+    from gatewaysdk.world_sessions import WorldSessionError
+    from gatewaysdk.world_tasks import list_tasks
+
+    pairs: Dict[str, str] = {}
+    for pair in metadata:
+        key, sep, value = pair.partition("=")
+        if not sep or not key:
+            typer.echo(f"--metadata {pair}: expected key=value", err=True)
+            raise typer.Exit(2)
+        pairs[key] = value
+    try:
+        listed = list_tasks(world=world, metadata=pairs or None, page=page, limit=limit, host=host)
+    except WorldSessionError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(1)
+    out = {
+        "tasks": [_task_result_json(task) for task in listed.tasks],
+        "meta": {
+            "page": listed.page,
+            "limit": listed.limit,
+            "totalItems": listed.total_items,
+            "totalPages": listed.total_pages,
+        },
+    }
+    typer.echo(json.dumps(out, indent=2))
+
+
+@task_app.command("show")
+def task_show(
+    task_id: str = typer.Argument(...),
+    version: Optional[int] = typer.Option(None, "--version", help="Show this version's spec instead of the current."),
+    host: Optional[str] = typer.Option(None, "--host", envvar="GATEWAY_HOST"),
+) -> None:
+    """One task: its current (or ``--version``) spec and its version history."""
+    from gatewaysdk.world_sessions import WorldSessionError
+    from gatewaysdk.world_tasks import get_task
+
+    try:
+        detail = get_task(task_id, version=version, host=host)
+    except WorldSessionError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(1)
+    typer.echo(json.dumps(_task_result_json(detail), indent=2))
+
+
+@task_app.command("validate")
+def task_validate(
+    task_id: str = typer.Argument(...),
+    version: Optional[int] = typer.Option(None, "--version", help="Validate this task version (default: current)."),
+    world: Optional[str] = typer.Option(None, "--world", "-w", help="Against this world's head version."),
+    version_id: Optional[str] = typer.Option(None, "--version-id", help="Against this exact world version."),
+    host: Optional[str] = typer.Option(None, "--host", envvar="GATEWAY_HOST"),
+) -> None:
+    """Check a task fits a world version — every seed and check entity exists
+    in its contract — without opening a session. Exit 1 when it does not."""
+    from gatewaysdk.world_sessions import WorldSessionError
+    from gatewaysdk.world_tasks import validate_task
+
+    if world and version_id:
+        typer.echo("--world and --version-id exclude each other", err=True)
+        raise typer.Exit(2)
+    try:
+        result = validate_task(task_id, version=version, slug=world, version_id=version_id, host=host)
+    except WorldSessionError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(1)
+    typer.echo(json.dumps(_task_result_json(result), indent=2))
+    if not result.ok:
+        raise typer.Exit(1)
+
+
+@task_app.command("delete")
+def task_delete(
+    task_id: str = typer.Argument(...),
+    host: Optional[str] = typer.Option(None, "--host", envvar="GATEWAY_HOST"),
+) -> None:
+    """Remove a stored task and all its versions. Open sessions keep their copy."""
+    from gatewaysdk.world_sessions import WorldSessionError
+    from gatewaysdk.world_tasks import delete_task
+
+    try:
+        typer.echo(json.dumps(delete_task(task_id, host=host), indent=2))
+    except WorldSessionError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(1)
+
+
+@bench_app.command("push")
+def bench_push(
+    path: str = typer.Argument(..., help="Path to the verifiers-format environment directory."),
+    slug: Optional[str] = typer.Option(None, "--slug", help="Container slug (defaults to the directory name)."),
+    name: Optional[str] = typer.Option(None, "--name", help="Human-readable container name."),
+    description: Optional[str] = typer.Option(None, "--description", help="Container description."),
+    tag: Optional[List[str]] = typer.Option(None, "--tag", help="Tag (repeatable)."),
+    visibility: Optional[str] = typer.Option(None, "--visibility", help="PRIVATE or PUBLIC."),
+    auto_bump: bool = typer.Option(False, "--auto-bump", help="Patch-bump pyproject version before pushing."),
+    rc: bool = typer.Option(False, "--rc", help="Bump/create an .rc pre-release before pushing."),
+    post: bool = typer.Option(False, "--post", help="Bump/create a .post release before pushing."),
+    image: Optional[str] = typer.Option(
+        None,
+        "--image",
+        help="Pre-built OCI image ref for image/agentic envs (recorded on the version).",
+    ),
+    build_wheel: bool = typer.Option(
+        False,
+        "--build-wheel",
+        help="Build a wheel (uv build --wheel) + upload it for pip-install-by-name.",
+    ),
+    branch: Optional[str] = typer.Option(
+        None,
+        "--branch",
+        "-b",
+        help="Branch to push to (default: the dir's tracked branch, else main).",
+    ),
+    force: bool = typer.Option(
+        False,
+        "--force",
+        help="Skip the fast-forward check (move the branch even if it diverged).",
+    ),
+    message: Optional[str] = typer.Option(None, "--message", "-m", help="Change reason, shown in History."),
+    author: Optional[str] = typer.Option(
+        None, "--author", help="Attribution shown in History (default: GATEWAY_AUTHOR env)."
+    ),
+    host: Optional[str] = typer.Option(None, "--host", envvar="GATEWAY_HOST"),
+) -> None:
+    """Push a benchmark container to Gateway as a content-hashed source bundle.
+
+    The dir's ``.gateway/.env-metadata.json`` (written by pull/push) supplies the
+    BASE version — pushing onto a branch whose tip moved refuses with a 409
+    ("pull/rebase, use another --branch, or --force"). ``--auto-bump/--rc/--post``
+    (mutually exclusive) rewrite ``[project].version`` in pyproject.toml before
+    hashing, so the bump lands in the bundle.
+
+    Examples::
+
+        gateway bench push ./automationbench -m "tighten grader"
+        gateway bench push ./automationbench --branch wip-alice
+        gateway bench push ./automationbench --auto-bump
+    """
+    import os as _os
+    import shutil as _shutil
+    import tempfile as _tempfile
+
+    from gatewaysdk.benchmark_hub import GatewayBenchmarkClient
+    from gatewaysdk.environment.schema import bundle_mode
+    from gatewaysdk.environment.schema.api import build_api_bundle
+
+    client = GatewayBenchmarkClient.from_env(host)
+    source = Path(path)
+    # A schema world that describes a vendor connection is pushed AS the api-kind bundle
+    # that serves it: the world stays the authority, the packaging is not the user's job.
+    serves_api = (source / "connector.toml").is_file() and bundle_mode(source) is not None
+    staging = _tempfile.TemporaryDirectory(prefix="gateway-world-api-") if serves_api else None
+    if serves_api:
+        bundle = build_api_bundle(source, Path(staging.name) / "bundle")
+        if (source / ".gateway").is_dir():
+            _shutil.copytree(source / ".gateway", bundle / ".gateway")
+        path = str(bundle)
+        slug = slug or source.resolve().name
+    result = client.push(
+        path,
+        slug=slug,
+        name=name,
+        description=description,
+        tags=tag,
+        visibility=visibility,
+        auto_bump=auto_bump,
+        rc=rc,
+        post=post,
+        image_ref=image,
+        wheel=build_wheel,
+        branch=branch,
+        force=force,
+        message=message,
+        author=author or _os.environ.get("GATEWAY_AUTHOR"),
+    )
+    if serves_api:
+        meta = Path(path) / ".gateway"
+        if meta.is_dir():
+            _shutil.rmtree(source / ".gateway", ignore_errors=True)
+            _shutil.copytree(meta, source / ".gateway")
+        staging.cleanup()
+    typer.echo(json.dumps(result, indent=2))
+
+
+@bench_app.command("install")
+def bench_install(
+    slug: str = typer.Argument(..., help="Container slug, optionally slug@latest | @<semver> | @<hash>."),
+    tool: str = typer.Option("uv", "--tool", help="Installer: uv or pip."),
+    no_upgrade: bool = typer.Option(False, "--no-upgrade", help="Don't reinstall/upgrade if already present."),
+    host: Optional[str] = typer.Option(None, "--host", envvar="GATEWAY_HOST"),
+) -> None:
+    """pip-install a container version's built wheel by name (wheel-url-direct).
+
+    The version must have been pushed with ``--build-wheel``. Runs in the current
+    Python environment (activate a venv first for uv).
+
+    Examples::
+
+        gateway bench install automationbench@1.2.0
+    """
+    from gatewaysdk.benchmark_hub import GatewayBenchmarkClient
+
+    client = GatewayBenchmarkClient.from_env(host)
+    result = client.install(slug, tool=tool, no_upgrade=no_upgrade)
+    typer.echo(json.dumps(result, indent=2))
+
+
+def _reject_mock_tools() -> None:
+    """`bench eval` runs verifiers and harbor world types; a ``mock-tools``
+    bundle (a ``gateway-env.toml`` world) is executed by the local runtime
+    instead."""
+    typer.echo(
+        "this container is a mock-tools world (gateway-env.toml) — "
+        "`gateway bench eval` runs the verifiers and harbor world types only. "
+        "Run it locally with the environment runtime "
+        "(`import gatewaysdk.environment as gwenv; env = gwenv.init(<slug>)`), "
+        "or from the platform, whose hosted runner serves mock-tools worlds.",
+        err=True,
+    )
+    raise typer.Exit(1)
+
+
+def _reject_verifiers_v1() -> None:
+    """`bench eval` only runs the legacy v0 in-process path locally; verifiers
+    v1 Taskset packages run via the platform's verifiers-v1 world type."""
+    typer.echo(
+        "this container is a verifiers v1 Taskset package (verifiers.v1 "
+        "namespace) — `gateway bench eval` currently only runs the legacy v0 "
+        "in-process path locally. Run it from the platform (its hosted runner "
+        "handles the verifiers-v1 world type, including Anthropic-dialect "
+        "endpoints), or pin the env to verifiers<1.0.0 and expose a v0 "
+        "load_environment() for local eval.",
+        err=True,
+    )
+    raise typer.Exit(1)
+
+
+@bench_app.command("eval")
+def bench_eval(
+    slug: Optional[str] = typer.Argument(
+        None,
+        help="Container slug@ref to eval (install it first: `bench install`). Omit when using --path.",
+    ),
+    path: Optional[str] = typer.Option(
+        None,
+        "--path",
+        "-p",
+        help="Run a LOCAL world directory (harbor kind) instead of pulling a ref. A clean `bench checkout` files the run pinned to its base version; a drifted or unlinked dir runs without filing.",
+    ),
+    model: str = typer.Option(..., "--model", "-m", help="Model id for OpenRouter."),
+    env_id: Optional[str] = typer.Option(
+        None,
+        "--env-id",
+        help="verifiers env id to load (defaults to the slug).",
+    ),
+    kind: str = typer.Option(
+        "auto",
+        "--kind",
+        help="Environment kind: auto (pull + detect) | verifiers | verifiers-v1 | harbor.",
+    ),
+    agent: str = typer.Option(
+        "mini-swe-agent",
+        "--agent",
+        "-a",
+        help="harbor kind only: agent that runs the tasks (harbor agent name or acp: shorthand).",
+    ),
+    num_examples: int = typer.Option(-1, "--num-examples", "-n"),
+    rollouts: int = typer.Option(1, "--rollouts-per-example", "-r"),
+    save_results: bool = typer.Option(False, "--save-results", "-s", help="Write a resumable results dir."),
+    output_dir: str = typer.Option("./outputs", "--output-dir", "-o"),
+    resume: Optional[str] = typer.Option(None, "--resume", "-R", help="Resume from a results dir path."),
+    fail_under: Optional[float] = typer.Option(
+        None,
+        "--fail-under",
+        min=0.0,
+        max=1.0,
+        help="CI gate: exit 1 when the average reward lands below this bar (also fails when no aggregate is available). Writes a $GITHUB_STEP_SUMMARY table under GitHub Actions.",
+    ),
+    host: Optional[str] = typer.Option(None, "--host", envvar="GATEWAY_HOST"),
+) -> None:
+    """Run a local eval against a container version and harvest a version-pinned
+    evaluation to Gateway. Auto-detects the env kind from the bundle:
+
+    - verifiers kind: in-process rollout loop (requires ``verifiers`` + ``openai``
+      installed and the container installed via ``gateway bench install``).
+      ``--save-results`` writes ``outputs/evals/<env>--<model>/<run>/`` for
+      ``--resume``.
+    - harbor kind: runs the task dirs as a harbor world
+      (docker sandbox by default; each task grades itself via its tests/), then
+      harvests the jobs dir.
+
+    ``--path`` runs your working copy: the harbor runner executes the LOCAL
+    task dirs, and the result files only when the dir is a clean checkout
+    (its ``.gateway`` base matches the tree) — pinned to that base version,
+    branch tag included. A drifted tree runs but stays local, with the push
+    hint printed up front.
+
+    Requires ``OPENROUTER_API_KEY`` either way.
+    """
+    import os
+    import tempfile
+
+    from gatewaysdk.benchmark_hub import (
+        EvalConfig,
+        GatewayBenchmarkClient,
+        GatewayEvalsClient,
+        detect_env_kind,
+        find_mcp_config,
+        harvest_job_dir,
+        local_tree_state,
+        resolve_harbor_model,
+        run_harbor_job,
+        run_local_eval,
+        tasks_root,
+    )
+
+    if (slug is None) == (path is None):
+        typer.echo("pass exactly one of SLUG or --path", err=True)
+        raise typer.Exit(1)
+
+    api_key = os.environ.get("OPENROUTER_API_KEY")
+    if not api_key:
+        typer.echo("OPENROUTER_API_KEY is required for `bench eval`.", err=True)
+        raise typer.Exit(1)
+
+    if kind not in ("auto", "verifiers", "verifiers-v1", "harbor"):
+        typer.echo(
+            f"unknown --kind '{kind}' (auto|verifiers|verifiers-v1|harbor)",
+            err=True,
+        )
+        raise typer.Exit(1)
+    if kind == "verifiers-v1":
+        _reject_verifiers_v1()
+
+    if path is not None:
+        src = os.path.abspath(path)
+        if not os.path.isdir(src):
+            typer.echo(f"--path is not a directory: {path}", err=True)
+            raise typer.Exit(1)
+        resolved_kind = detect_env_kind(src) if kind == "auto" else kind
+        if resolved_kind == "mock-tools":
+            _reject_mock_tools()
+        if resolved_kind == "verifiers-v1":
+            _reject_verifiers_v1()
+        if resolved_kind == "verifiers":
+            typer.echo(
+                "--path runs harbor worlds; verifiers packages run from the " "hub (`gateway bench eval <slug>`).",
+                err=True,
+            )
+            raise typer.Exit(1)
+
+        # Filing is honest-or-off: only a CLEAN checkout pins its base
+        # version. Said up front — not after a long docker run.
+        state = local_tree_state(Path(src))
+        meta = state["meta"] or {}
+        file_version_id = meta.get("versionId") if state["clean"] else None
+        if file_version_id:
+            typer.echo(
+                f"filing to {meta.get('slug')}@{meta.get('branch') or meta.get('ref')} "
+                f"({str(meta.get('contentHash') or '')[:8]})",
+                err=True,
+            )
+        elif meta.get("versionId"):
+            dirty = state["dirty"]
+            shown = ", ".join(dirty[:5]) + (", …" if len(dirty) > 5 else "")
+            typer.echo(
+                f"note: {len(dirty)} file(s) differ from "
+                f"{meta.get('branch') or meta.get('ref')}@"
+                f"{str(meta.get('contentHash') or '')[:8]} ({shown}) — the run "
+                "executes your local code but will NOT be filed. Push first "
+                "(`gateway bench push`) to file it.",
+                err=True,
+            )
+        else:
+            typer.echo(
+                "note: this dir has no hub link (.gateway) — the run stays "
+                "local. Push it (`gateway bench push`) to file runs.",
+                err=True,
+            )
+
+        harbor_model = resolve_harbor_model(model, agent)
+        jobs_dir = os.path.join(output_dir, "harbor-jobs", f"local--{os.path.basename(src) or 'world'}")
+        run_harbor_job(
+            tasks_root(src),
+            jobs_dir,
+            model=harbor_model,
+            agent=agent,
+            num_examples=num_examples,
+            rollouts_per_example=rollouts,
+            extra_env={"OPENROUTER_API_KEY": api_key},
+            mcp_config=find_mcp_config(src),
+        )
+        if file_version_id:
+            result = harvest_job_dir(
+                jobs_dir,
+                file_version_id,
+                GatewayEvalsClient.from_env(host),
+                model=harbor_model,
+                rollouts_per_example=rollouts,
+            )
+        else:
+            # Unfiled runs still aggregate locally — the CI gate and the
+            # printed result must not depend on filing.
+            from gatewaysdk.benchmark_hub.harbor_adapter import (
+                metrics_from_samples,
+                samples_from_job_dir,
+            )
+
+            local_samples = samples_from_job_dir(jobs_dir)
+            result = {
+                "jobsDir": jobs_dir,
+                "filed": False,
+                "metrics": metrics_from_samples(local_samples) if local_samples else {},
+            }
+        typer.echo(json.dumps(result, indent=2))
+        _ci_finish(
+            result,
+            fail_under=fail_under,
+            title=f"World eval · {os.path.basename(src)} (local)",
+            facts=[("model", harbor_model), ("agent", agent)],
+        )
+        return
+
+    bench = GatewayBenchmarkClient.from_env(host)
+    ref_slug, ref = slug.rsplit("@", 1) if "@" in slug else (slug, "latest")
+    details = bench.resolve_version(ref_slug, ref)
+    version_id = details["versionId"]
+
+    with tempfile.TemporaryDirectory(prefix="gateway-bench-eval-") as td:
+        src: Optional[str] = None
+        if kind in ("auto", "harbor"):
+            src = os.path.join(td, "src")
+            bench.pull(f"{ref_slug}@{ref}", target=src)
+            resolved_kind = detect_env_kind(src) if kind == "auto" else "harbor"
+        else:
+            resolved_kind = "verifiers"
+
+        if resolved_kind == "mock-tools":
+            _reject_mock_tools()
+        if resolved_kind == "verifiers-v1":
+            _reject_verifiers_v1()
+
+        if resolved_kind == "harbor":
+            assert src is not None
+            harbor_model = resolve_harbor_model(model, agent)
+            jobs_dir = os.path.join(output_dir, "harbor-jobs", f"{ref_slug}--{ref}")
+            run_harbor_job(
+                tasks_root(src),
+                jobs_dir,
+                model=harbor_model,
+                agent=agent,
+                num_examples=num_examples,
+                rollouts_per_example=rollouts,
+                extra_env={"OPENROUTER_API_KEY": api_key},
+                # Env-bundled Claude-style MCP config (e.g. enterpriseops-*:
+                # the gym's tools + x-database-id header) — auto-detected.
+                mcp_config=find_mcp_config(src),
+            )
+            result = harvest_job_dir(
+                jobs_dir,
+                version_id,
+                GatewayEvalsClient.from_env(host),
+                model=harbor_model,
+                rollouts_per_example=rollouts,
+            )
+            typer.echo(json.dumps(result, indent=2))
+            _ci_finish(
+                result,
+                fail_under=fail_under,
+                title=f"World eval · {ref_slug}@{ref}",
+                facts=[("model", harbor_model), ("agent", agent)],
+            )
+            return
+
+    try:
+        # verifiers' rollout loop is async — newer releases reject a sync
+        # OpenAI client outright ("Unsupported client type").
+        from openai import AsyncOpenAI
+    except ImportError:
+        typer.echo("openai is required: pip install openai", err=True)
+        raise typer.Exit(1)
+
+    client = AsyncOpenAI(base_url="https://openrouter.ai/api/v1", api_key=api_key)
+    config = EvalConfig(
+        env_id=env_id or ref_slug,
+        model=model,
+        num_examples=num_examples,
+        rollouts_per_example=rollouts,
+        save_results=save_results or resume is not None,
+        output_dir=output_dir,
+        resume_path=resume,
+    )
+    result = run_local_eval(
+        config.env_id,
+        version_id,
+        GatewayEvalsClient.from_env(host),
+        client=client,
+        config=config,
+    )
+    typer.echo(json.dumps(result, indent=2))
+    _ci_finish(
+        result,
+        fail_under=fail_under,
+        title=f"World eval · {ref_slug}@{ref}",
+        facts=[("model", model)],
+    )
+
+
+@bench_app.command("harvest-harbor")
+def bench_harvest_harbor(
+    jobs_dir: str = typer.Argument(..., help="A completed harbor (or pier) jobs directory."),
+    slug: str = typer.Argument(..., help="Container slug@ref the evaluation pins to."),
+    model: str = typer.Option(..., "--model", "-m", help="Model id the job ran with."),
+    rollouts: int = typer.Option(1, "--rollouts-per-example", "-r"),
+    run_id: Optional[str] = typer.Option(None, "--run-id", help="Environment RunResult id to back-link."),
+    host: Optional[str] = typer.Option(None, "--host", envvar="GATEWAY_HOST"),
+) -> None:
+    """Harvest an EXISTING harbor jobs directory into a version-pinned Gateway
+    evaluation (harvest-only twin of `bench eval --kind harbor`)."""
+    from gatewaysdk.benchmark_hub import (
+        GatewayBenchmarkClient,
+        GatewayEvalsClient,
+        harvest_job_dir,
+    )
+
+    bench = GatewayBenchmarkClient.from_env(host)
+    ref_slug, ref = slug.rsplit("@", 1) if "@" in slug else (slug, "latest")
+    version_id = bench.resolve_version(ref_slug, ref)["versionId"]
+    result = harvest_job_dir(
+        jobs_dir,
+        version_id,
+        GatewayEvalsClient.from_env(host),
+        model=model,
+        run_id=run_id,
+        rollouts_per_example=rollouts,
+    )
+    typer.echo(json.dumps(result, indent=2))
+
+
+@bench_app.command("run-configs")
+def bench_run_configs(
+    action: str = typer.Argument("list", help="list | create | delete"),
+    name: Optional[str] = typer.Option(None, "--name", help="Config name (create)."),
+    models: Optional[str] = typer.Option(None, "--models", help="Comma-separated model list (create)."),
+    parallelism: int = typer.Option(1, "--parallelism", help="Containers per model, 1-16 (create)."),
+    tasks: Optional[str] = typer.Option(None, "--tasks", help="Comma-separated bundled task names (create)."),
+    world_tasks: Optional[str] = typer.Option(
+        None,
+        "--world-tasks",
+        help="Comma-separated stored task refs, <id> or <id>@<version> (create; api worlds, not with --tasks).",
+    ),
+    agent: Optional[str] = typer.Option(None, "--agent", help="harbor agent (create)."),
+    auto_run_on_push: bool = typer.Option(
+        False, "--auto-run-on-push", help="Dispatch on every pushed READY version (create)."
+    ),
+    config_id: Optional[str] = typer.Option(None, "--id", help="Config id (delete/update)."),
+    host: Optional[str] = typer.Option(None, "--host", envvar="GATEWAY_HOST"),
+) -> None:
+    """Run configs from the CLI — list them, create one for CI, delete one.
+
+    gateway bench run-configs list
+    gateway bench run-configs create --name ci-suite --models openai/gpt-5-mini --parallelism 4
+    gateway bench run-configs create --name stored --models openai/gpt-5-mini --world-tasks wt_a,wt_b@2
+    gateway bench run-configs delete --id cmrc123
+    """
+    from ..benchmark_hub.client import GatewayBenchmarkClient
+    from ..world_tasks import parse_world_task_refs
+
+    client = GatewayBenchmarkClient.from_env(host)
+    if action == "list":
+        rows = client.list_run_configs().get("runConfigs", [])
+        if not rows:
+            typer.echo("No run configs in this project.")
+            return
+        for row in rows:
+            flags = []
+            if row.get("parallelism", 1) > 1:
+                flags.append(f"x{row['parallelism']} containers")
+            if row.get("autoRunOnPush"):
+                flags.append("auto-on-push")
+            suffix = f"  [{', '.join(flags)}]" if flags else ""
+            typer.echo(f"{row['id']}  {row['name']}  ({', '.join(row.get('models', []) or ['no models'])}){suffix}")
+        return
+    if action == "delete":
+        if not config_id:
+            raise typer.BadParameter("--id is required for delete")
+        client.delete_run_config(config_id)
+        typer.echo(f"Deleted {config_id}.")
+        return
+    if action != "create":
+        raise typer.BadParameter("action must be one of: list | create | delete")
+    if not name or not models:
+        raise typer.BadParameter("--name and --models are required for create")
+    fields: Dict[str, Any] = {
+        "name": name,
+        "models": [m.strip() for m in models.split(",") if m.strip()],
+        "parallelism": parallelism,
+    }
+    if agent:
+        fields["agent"] = agent
+    if tasks:
+        fields["taskNames"] = [t.strip() for t in tasks.split(",") if t.strip()]
+    if world_tasks:
+        if tasks:
+            raise typer.BadParameter(
+                "--tasks and --world-tasks are exclusive: a config runs bundled scenarios or stored tasks"
+            )
+        try:
+            fields["worldTasks"] = parse_world_task_refs(world_tasks)
+        except ValueError as exc:
+            raise typer.BadParameter(str(exc)) from exc
+    if auto_run_on_push:
+        fields["autoRunOnPush"] = True
+    if config_id:
+        fields["id"] = config_id
+    row = client.upsert_run_config(**fields)
+    typer.echo(f"{row['id']}  {row['name']}  ({', '.join(row.get('models', []))})")
+
+
+@bench_app.command("secrets")
+def bench_secrets(
+    action: str = typer.Argument(..., help="set | list | unset"),
+    env: str = typer.Option(..., "--env", help="World slug the secret belongs to."),
+    key: Optional[str] = typer.Option(None, "--key", help="Secret name (UPPER_SNAKE_CASE) — required for set/unset."),
+    value: Optional[str] = typer.Option(
+        None, "--value", help="Secret value for `set`; omit to read from stdin (keeps it out of shell history)."
+    ),
+    host: Optional[str] = typer.Option(None, "--host", envvar="GATEWAY_HOST"),
+) -> None:
+    """Environment secrets — env vars every HOSTED run of the world receives.
+
+    Write-only: `list` shows names and rotation times, never values.
+
+        gateway bench secrets set --env blockchain-investigator --key ETHERSCAN_API_KEY
+        gateway bench secrets list --env blockchain-investigator
+        gateway bench secrets unset --env blockchain-investigator --key ETHERSCAN_API_KEY
+    """
+    import sys
+
+    from ..benchmark_hub.client import GatewayBenchmarkClient
+
+    client = GatewayBenchmarkClient.from_env(host)
+    if action == "list":
+        rows = client.list_env_secret_keys(env).get("secrets", [])
+        if not rows:
+            typer.echo(f"No secrets on {env}.")
+            return
+        for row in rows:
+            typer.echo(f"{row['key']}  (rotated {row['updatedAt']})")
+        return
+    if action not in ("set", "unset"):
+        raise typer.BadParameter("action must be one of: set | list | unset")
+    if not key:
+        raise typer.BadParameter(f"--key is required for `{action}`")
+    if action == "unset":
+        client.delete_env_secret(env, key)
+        typer.echo(f"Deleted {key} from {env}.")
+        return
+    secret = value
+    if secret is None:
+        typer.echo(f"Value for {key} (input hidden): ", nl=False, err=True)
+        secret = sys.stdin.readline().strip() if not sys.stdin.isatty() else __import__("getpass").getpass("")
+    if not secret:
+        raise typer.BadParameter("empty value — nothing stored")
+    res = client.set_env_secret(env, key, secret)
+    typer.echo(f"{'Added' if res.get('created') else 'Rotated'} {key} on {env} — next hosted run receives it.")
+
+
+@bench_app.command("dispatch")
+def bench_dispatch(
+    run_config_id: str = typer.Argument(..., help="Run config id (world page -> Runs -> Configs)."),
+    container_id: Optional[str] = typer.Option(
+        None, "--container-id", help="Which environment, when the project hosts several."
+    ),
+    version_id: Optional[str] = typer.Option(
+        None, "--version-id", help="Pin to a specific READY version (default: head)."
+    ),
+    host: Optional[str] = typer.Option(None, "--host", envvar="GATEWAY_HOST"),
+) -> None:
+    """Start a hosted run of a run config — the same dispatch the Run button
+    uses, parallelism included: the config's `parallelism` fans the task list
+    across that many containers per model.
+
+    Examples::
+
+        gateway bench dispatch cmrunconfig123
+        gateway bench dispatch cmrunconfig123 --version-id cmversion456
+    """
+    from gatewaysdk.benchmark_hub import GatewayBenchmarkClient
+
+    client = GatewayBenchmarkClient.from_env(host)
+    result = client.dispatch_run_config(run_config_id, container_id=container_id, version_id=version_id)
+    typer.echo(json.dumps(result, indent=2))
+
+
+@bench_app.command("pull")
+def bench_pull(
+    slug: str = typer.Argument(
+        ...,
+        help="Container slug, optionally slug@latest | @<semver> | @<hash-prefix>.",
+    ),
+    target: Optional[str] = typer.Option(None, "--target", "-t", help="Target dir (defaults to ./<slug>)."),
+    host: Optional[str] = typer.Option(None, "--host", envvar="GATEWAY_HOST"),
+) -> None:
+    """Reconstruct a container version's source directory, addressed by name.
+
+    Examples::
+
+        gateway bench pull automationbench
+        gateway bench pull automationbench@1.2.0 --target ./ab
+    """
+    from gatewaysdk.benchmark_hub import GatewayBenchmarkClient
+
+    client = GatewayBenchmarkClient.from_env(host)
+    result = client.pull(slug, target=target)
+    typer.echo(json.dumps(result, indent=2))
+
+
+@bench_app.command("fork")
+def bench_fork(
+    slug: str = typer.Argument(..., help="Source container slug (forks the head; omit @version)."),
+    into: Optional[str] = typer.Option(None, "--into", help="Target slug (defaults to <slug>-fork)."),
+    host: Optional[str] = typer.Option(None, "--host", envvar="GATEWAY_HOST"),
+) -> None:
+    """Fork a container into a new one (shares the immutable, content-addressed
+    bundle; records provenance via forkedFromVersionId).
+
+    Examples::
+
+        gateway bench fork automationbench --into automationbench-v2
+    """
+    from gatewaysdk.benchmark_hub import GatewayBenchmarkClient
+
+    client = GatewayBenchmarkClient.from_env(host)
+    result = client.fork(slug, target_slug=into)
+    typer.echo(json.dumps(result, indent=2))
+
+
+@bench_app.command("status")
+def bench_status(
+    path: str = typer.Argument(".", help="Working dir (defaults to cwd)."),
+    host: Optional[str] = typer.Option(None, "--host", envvar="GATEWAY_HOST"),
+) -> None:
+    """Where this dir stands: tracked branch, base version, local edits
+    (dirty), and whether the remote branch tip moved past the base (behind).
+
+    Examples::
+
+        gateway bench status
+        gateway bench status ./automationbench
+    """
+    from gatewaysdk.benchmark_hub import GatewayBenchmarkClient
+
+    client = GatewayBenchmarkClient.from_env(host)
+    result = client.status(path)
+    typer.echo(json.dumps(result, indent=2))
+    if result.get("dirty"):
+        typer.echo("# local edits not pushed", err=True)
+    if result.get("behind"):
+        typer.echo(
+            "# branch tip moved past your base — `gateway bench pull` before pushing",
+            err=True,
+        )
+
+
+@bench_app.command("log")
+def bench_log(
+    slug: str = typer.Argument(..., help="Container slug."),
+    branch: Optional[str] = typer.Option(None, "--branch", "-b", help="Branch (default main)."),
+    limit: int = typer.Option(20, "--limit", "-n", help="Max entries."),
+    host: Optional[str] = typer.Option(None, "--host", envvar="GATEWAY_HOST"),
+) -> None:
+    """A branch's version lineage, tip first — hash, semver, author, reason.
+
+    Examples::
+
+        gateway bench log automationbench
+        gateway bench log automationbench --branch wip-alice -n 50
+    """
+    from gatewaysdk.benchmark_hub import GatewayBenchmarkClient
+
+    client = GatewayBenchmarkClient.from_env(host)
+    result = client.log(slug, branch=branch, limit=limit)
+    typer.echo(json.dumps(result, indent=2))
+
+
+@bench_app.command("branch")
+def bench_branch(
+    name: Optional[str] = typer.Argument(None, help="Create a branch with this name (omit to list)."),
+    path: str = typer.Option(".", "--path", help="Working dir whose container/branch to use."),
+    slug: Optional[str] = typer.Option(None, "--slug", help="Container slug (default: the dir's tracked slug)."),
+    from_version: Optional[str] = typer.Option(None, "--from", help="Start version id (default: the main tip)."),
+    host: Optional[str] = typer.Option(None, "--host", envvar="GATEWAY_HOST"),
+) -> None:
+    """List branches/tags (the dir's current branch marked with *), or create one.
+
+    Examples::
+
+        gateway bench branch                     # list, current marked *
+        gateway bench branch wip-alice           # create from main tip
+        gateway bench branch hotfix --from <versionId>
+    """
+    from gatewaysdk.benchmark_hub import GatewayBenchmarkClient, read_local_meta
+
+    client = GatewayBenchmarkClient.from_env(host)
+    meta = read_local_meta(Path(path)) or {}
+    resolved_slug = slug or meta.get("slug")
+    if not resolved_slug:
+        typer.echo("Error: no --slug and this dir tracks no container (pull first).", err=True)
+        raise typer.Exit(1)
+
+    if name:
+        result = client.create_ref(resolved_slug, name, kind="branch", version_id=from_version)
+        typer.echo(json.dumps(result, indent=2))
+        return
+
+    refs = client.list_refs(resolved_slug)
+    current = meta.get("branch") if meta.get("slug") == resolved_slug else None
+    for ref in refs.get("refs", []):
+        marker = "*" if ref.get("kind") == "branch" and ref.get("name") == current else " "
+        semver = ref.get("semanticVersion") or ""
+        typer.echo(
+            f"{marker} {ref.get('kind'):<6} {ref.get('name'):<24} "
+            f"{(ref.get('contentHash') or '')[:12]:<12} {semver}"
+        )
+
+
+@bench_app.command("checkout")
+def bench_checkout(
+    slug_ref: str = typer.Argument(..., help="slug@<branch|tag|semver|hash> (bare slug = main)."),
+    target: Optional[str] = typer.Option(None, "--target", "-t", help="Target dir (defaults to ./<slug>)."),
+    host: Optional[str] = typer.Option(None, "--host", envvar="GATEWAY_HOST"),
+) -> None:
+    """Materialize a ref into a working dir and track it (pull + set base).
+
+    Examples::
+
+        gateway bench checkout automationbench@wip-alice
+        gateway bench checkout automationbench@v1.2.0 -t ./ab-1.2
+    """
+    from gatewaysdk.benchmark_hub import GatewayBenchmarkClient
+
+    client = GatewayBenchmarkClient.from_env(host)
+    result = client.pull(slug_ref, target=target)
+    typer.echo(json.dumps(result, indent=2))
+
+
+@bench_app.command("tag")
+def bench_tag(
+    name: str = typer.Argument(..., help="Tag name (immutable)."),
+    path: str = typer.Option(".", "--path", help="Working dir whose container to use."),
+    slug: Optional[str] = typer.Option(None, "--slug", help="Container slug (default: the dir's tracked slug)."),
+    version: Optional[str] = typer.Option(None, "--version", help="Version id to tag (default: main tip)."),
+    host: Optional[str] = typer.Option(None, "--host", envvar="GATEWAY_HOST"),
+) -> None:
+    """Create an immutable tag pointing at a version.
+
+    Examples::
+
+        gateway bench tag v1.0.0
+        gateway bench tag baseline --version <versionId>
+    """
+    from gatewaysdk.benchmark_hub import GatewayBenchmarkClient, read_local_meta
+
+    client = GatewayBenchmarkClient.from_env(host)
+    resolved_slug = slug or (read_local_meta(Path(path)) or {}).get("slug")
+    if not resolved_slug:
+        typer.echo("Error: no --slug and this dir tracks no container (pull first).", err=True)
+        raise typer.Exit(1)
+    result = client.create_ref(resolved_slug, name, kind="tag", version_id=version)
+    typer.echo(json.dumps(result, indent=2))
+
+
+@bench_app.command("propose")
+def bench_propose(
+    path: str = typer.Argument(".", help="Working dir with local edits."),
+    title: str = typer.Option(..., "--title", help="Proposal title, shown to the reviewer."),
+    message: str = typer.Option(..., "--message", "-m", help="Why this changeset."),
+    branch: Optional[str] = typer.Option(
+        None, "--branch", "-b", help="Branch the proposal merges into (default main)."
+    ),
+    host: Optional[str] = typer.Option(None, "--host", envvar="GATEWAY_HOST"),
+) -> None:
+    """File local edits as a change proposal (a PR to the env) instead of
+    pushing to the branch — review + apply happen on the environment homepage.
+
+    Examples::
+
+        gateway bench propose --title "Harden verifier" -m "SQL check missed nulls"
+    """
+    from gatewaysdk.benchmark_hub import GatewayBenchmarkClient
+
+    client = GatewayBenchmarkClient.from_env(host)
+    result = client.propose(path, title=title, message=message, target_branch=branch)
+    typer.echo(json.dumps(result, indent=2))
+
+
+@bench_app.command("diff")
+def bench_diff(
+    base: str = typer.Argument(..., help="Base version id."),
+    head: str = typer.Argument(..., help="Head version id."),
+    host: Optional[str] = typer.Option(None, "--host", envvar="GATEWAY_HOST"),
+) -> None:
+    """Per-file diff (added/removed/modified/unchanged) between two version ids."""
+    from gatewaysdk.benchmark_hub import GatewayBenchmarkClient
+
+    client = GatewayBenchmarkClient.from_env(host)
+    result = client.diff(base, head)
+    typer.echo(json.dumps(result, indent=2))
+
+
+environment_app = typer.Typer(
+    name="environment",
+    help="Environment hub — inspect environments, task sets, rollouts, and the Environment Agent.",
+    no_args_is_help=True,
+)
+app.add_typer(environment_app, name="environment")
+
+
+@environment_app.command("list")
+def environment_list(
+    slug: Optional[str] = typer.Option(None, "--slug", help="Filter to one environment slug."),
+    limit: int = typer.Option(50, "--limit", "-n", help="Max environments to list."),
+    host: Optional[str] = typer.Option(None, "--host", envvar="GATEWAY_HOST"),
+) -> None:
+    """List the project's environments (id, slug, latest version, task-set link)."""
+    from gatewaysdk.environments import GatewayEnvironmentClient
+
+    client = GatewayEnvironmentClient.from_env(host)
+    result = client.list_environments(slug=slug, limit=limit)
+    typer.echo(json.dumps(result.model_dump(), indent=2))
+
+
+@environment_app.command("get")
+def environment_get(
+    container_id: str = typer.Argument(..., help="Environment (container) id."),
+    host: Optional[str] = typer.Option(None, "--host", envvar="GATEWAY_HOST"),
+) -> None:
+    """Show one environment with its version history and rollout count."""
+    from gatewaysdk.environments import GatewayEnvironmentClient
+
+    client = GatewayEnvironmentClient.from_env(host)
+    result = client.get_environment(container_id)
+    typer.echo(json.dumps(result.model_dump(), indent=2))
+
+
+@environment_app.command("tasks")
+def environment_tasks(
+    container_id: str = typer.Argument(..., help="Environment (container) id."),
+    host: Optional[str] = typer.Option(None, "--host", envvar="GATEWAY_HOST"),
+) -> None:
+    """Show the environment's linked task set and its tasks."""
+    from gatewaysdk.environments import GatewayEnvironmentClient
+
+    client = GatewayEnvironmentClient.from_env(host)
+    result = client.get_task_set(container_id)
+    typer.echo(json.dumps(result.model_dump(), indent=2))
+
+
+def _resolve_environment_id(client: Any, ref: str) -> str:
+    """Accept a container id OR a slug everywhere an environment is named.
+
+    Ids are opaque cuids; slugs are what the UI and bundle manifests show —
+    a CLI that only takes the one you don't have is a lookup errand."""
+    listing = client.list_environments(slug=ref, limit=5)
+    for env in listing.environments:
+        if env.slug == ref:
+            return env.id
+    return ref
+
+
+@environment_app.command("run")
+def environment_run(
+    environment: str = typer.Argument(..., help="Environment slug or container id."),
+    model: List[str] = typer.Option(
+        ...,
+        "--model",
+        "-m",
+        help=(
+            "Model to run, repeatable. Use a provider-prefixed id — the "
+            "dispatch credential ladder resolves by prefix: `anthropic/...`, "
+            "`openrouter/vendor/model`, `gateway/vendor/model` "
+            "(platform-funded), or `bedrock/...`. Example: "
+            "-m openrouter/z-ai/glm-5.2 -m anthropic/claude-sonnet-4-6"
+        ),
+    ),
+    version_id: Optional[str] = typer.Option(None, "--version-id", help="Pin a READY version (default: newest)."),
+    num_examples: Optional[int] = typer.Option(None, "--num-examples", "-n", help="Cap scenarios (default: all)."),
+    rollouts: Optional[int] = typer.Option(None, "--rollouts", "-k", help="Rollouts per scenario (default 1)."),
+    wait: bool = typer.Option(True, "--wait/--no-wait", help="Block until every run settles and print verdicts."),
+    wait_timeout: int = typer.Option(1200, "--wait-timeout", help="Seconds to wait before giving up (with --wait)."),
+    host: Optional[str] = typer.Option(None, "--host", envvar="GATEWAY_HOST"),
+) -> None:
+    """Dispatch hosted rollouts — one runner job per model — and (by default)
+    wait for the verdicts. The same dispatch the world page's Run button uses.
+
+    Examples::
+
+        gateway environment run slack-legal -m openrouter/z-ai/glm-5.2
+        gateway environment run slack-legal -m gateway/openai/gpt-5-mini --no-wait
+    """
+    import time as _time
+
+    from gatewaysdk.environments import GatewayEnvironmentClient
+
+    client = GatewayEnvironmentClient.from_env(host)
+    container_id = _resolve_environment_id(client, environment)
+    dispatch = client.run_evaluation(
+        container_id,
+        models=list(model),
+        version_id=version_id,
+        num_examples=num_examples,
+        rollouts_per_example=rollouts,
+    )
+    typer.echo(json.dumps(dispatch.model_dump(), indent=2))
+    dispatched = [r for r in dispatch.runs if r.ok and r.runId]
+    if any(not r.ok for r in dispatch.runs):
+        for r in dispatch.runs:
+            if not r.ok:
+                typer.echo(f"# {r.model}: {r.error}", err=True)
+    if not wait or not dispatched:
+        raise typer.Exit(0 if dispatched else 1)
+
+    deadline = _time.time() + wait_timeout
+    failed = False
+    for r in dispatched:
+        while True:
+            budget = int(min(45, max(0, deadline - _time.time())))
+            verdict = client.get_run(r.runId, wait_seconds=budget)
+            if verdict.settled:
+                typer.echo(f"{r.model}: {verdict.status} avgReward={verdict.avgReward}")
+                for rollout in verdict.rollouts:
+                    typer.echo(f"  {rollout.task}: {rollout.reward} {json.dumps(rollout.verifiers)}")
+                failed = failed or verdict.status.upper() not in ("COMPLETED", "SUCCEEDED")
+                break
+            if _time.time() >= deadline:
+                typer.echo(f"{r.model}: still running after {wait_timeout}s (runId={r.runId})", err=True)
+                failed = True
+                break
+    raise typer.Exit(1 if failed else 0)
+
+
+@environment_app.command("run-status")
+def environment_run_status(
+    run_id: str = typer.Argument(..., help="Run id from `environment run` / dispatch."),
+    wait: int = typer.Option(0, "--wait", "-w", help="Block server-side up to N seconds (max 50) for it to settle."),
+    host: Optional[str] = typer.Option(None, "--host", envvar="GATEWAY_HOST"),
+) -> None:
+    """One run's verdict: status, avgReward, settled, per-task rollouts.
+
+    `settled: false` after a wait means keep polling — it is not failure.
+    """
+    from gatewaysdk.environments import GatewayEnvironmentClient
+
+    client = GatewayEnvironmentClient.from_env(host)
+    result = client.get_run(run_id, wait_seconds=wait)
+    typer.echo(json.dumps(result.model_dump(), indent=2))
+
+
+@environment_app.command("link-task-set")
+def environment_link_task_set(
+    environment: str = typer.Argument(..., help="Environment slug or container id."),
+    tasks: Optional[str] = typer.Option(
+        None, "--tasks", help="tasks.jsonl to fill the set from (rows: id, prompt, metadata, worlds)."
+    ),
+    name: Optional[str] = typer.Option(None, "--name", help="Task-set name (default: '<slug> scenarios')."),
+    description: Optional[str] = typer.Option(None, "--description", help="Task-set description."),
+    fresh: bool = typer.Option(False, "--fresh", help="Always create a new set instead of reusing the linked one."),
+    detach: bool = typer.Option(False, "--detach", help="Unlink the environment's task set and exit."),
+    host: Optional[str] = typer.Option(None, "--host", envvar="GATEWAY_HOST"),
+) -> None:
+    """Create/fill a scenario set and attach it — the command the world page's
+    empty state names. Idempotent: reuses the linked set and skips tasks whose
+    names already exist.
+
+    Examples::
+
+        gateway environment link-task-set qualtrics-suite --tasks tasks.jsonl
+        gateway environment link-task-set qualtrics-suite --detach
+    """
+    from gatewaysdk.environments import GatewayEnvironmentClient
+
+    client = GatewayEnvironmentClient.from_env(host)
+    container_id = _resolve_environment_id(client, environment)
+
+    if detach:
+        result = client.link_task_set(container_id, None)
+        typer.echo(json.dumps(result.model_dump(), indent=2))
+        return
+
+    existing: set = set()
+    dataset_id: Optional[str] = None
+    if not fresh:
+        try:
+            current = client.get_task_set(container_id)
+            dataset_id = current.datasetId
+            existing = {t.name for t in current.tasks}
+            typer.echo(f"# reusing linked task set {dataset_id}", err=True)
+        except Exception:
+            dataset_id = None
+    if dataset_id is None:
+        set_name = name or f"{environment} scenarios"
+        created = client.create_task_set(set_name, description=description)
+        dataset_id = created.datasetId
+        typer.echo(f"# created task set {dataset_id} ({set_name})", err=True)
+
+    if tasks:
+        for line in Path(tasks).read_text().splitlines():
+            if not line.strip():
+                continue
+            row = json.loads(line)
+            task_name = str(row.get("id") or row.get("task") or "")
+            if not task_name or task_name in existing:
+                continue
+            metadata = dict(row.get("metadata") or {})
+            if row.get("worlds") is not None:
+                metadata["worlds"] = row["worlds"]
+            client.create_task(dataset_id, task_name, str(row.get("prompt") or ""), metadata=metadata or None)
+            typer.echo(f"# task {task_name} created", err=True)
+
+    result = client.link_task_set(container_id, dataset_id)
+    typer.echo(json.dumps(result.model_dump(), indent=2))
+
+
+@environment_app.command("performance")
+def environment_performance(
+    container_id: str = typer.Argument(..., help="Environment (container) id."),
+    host: Optional[str] = typer.Option(None, "--host", envvar="GATEWAY_HOST"),
+) -> None:
+    """Show per-task performance across rollouts (nulls kept as their own category)."""
+    from gatewaysdk.environments import GatewayEnvironmentClient
+
+    client = GatewayEnvironmentClient.from_env(host)
+    result = client.get_performance(container_id)
+    typer.echo(json.dumps(result.model_dump(), indent=2))
+
+
+@environment_app.command("rollouts")
+def environment_rollouts(
+    container_id: str = typer.Argument(..., help="Environment (container) id."),
+    host: Optional[str] = typer.Option(None, "--host", envvar="GATEWAY_HOST"),
+) -> None:
+    """List the environment's rollouts (evaluations), newest first."""
+    from gatewaysdk.environments import GatewayEnvironmentClient
+
+    client = GatewayEnvironmentClient.from_env(host)
+    result = client.list_rollouts(container_id)
+    typer.echo(json.dumps(result.model_dump(), indent=2))
+
+
+@environment_app.command("samples")
+def environment_samples(
+    container_id: str = typer.Argument(..., help="Environment (container) id."),
+    evaluation_id: str = typer.Argument(..., help="Rollout (evaluation) id."),
+    limit: int = typer.Option(200, "--limit", "-n", help="Max samples to return."),
+    host: Optional[str] = typer.Option(None, "--host", envvar="GATEWAY_HOST"),
+) -> None:
+    """Show the scored samples of one rollout (reward/score/correct + sub-rewards)."""
+    from gatewaysdk.environments import GatewayEnvironmentClient
+
+    client = GatewayEnvironmentClient.from_env(host)
+    result = client.get_rollout_samples(container_id, evaluation_id, limit=limit)
+    typer.echo(json.dumps(result.model_dump(), indent=2))
+
+
+@environment_app.command("create-task")
+def environment_create_task(
+    dataset_id: str = typer.Argument(..., help="Task set dataset id (kind='tasks')."),
+    name: str = typer.Option(..., "--name", help="Task name."),
+    prompt: str = typer.Option(..., "--prompt", help="Task prompt."),
+    expected_output: Optional[str] = typer.Option(None, "--expected-output", help="Optional expected output."),
+    host: Optional[str] = typer.Option(None, "--host", envvar="GATEWAY_HOST"),
+) -> None:
+    """Create a task in a task set (a kind='tasks' dataset item). Requires a secret key.
+
+    The task set dataset id is on the environment (``environment get`` →
+    ``taskSetDatasetId``) or on ``environment tasks`` (→ ``datasetId``).
+    """
+    from gatewaysdk.environments import GatewayEnvironmentClient
+
+    client = GatewayEnvironmentClient.from_env(host)
+    result = client.create_task(dataset_id, name, prompt, expected_output=expected_output)
+    typer.echo(json.dumps(result.model_dump(), indent=2))
+
+
+@environment_app.command("agent-status")
+def environment_agent_status(
+    host: Optional[str] = typer.Option(None, "--host", envvar="GATEWAY_HOST"),
+) -> None:
+    """Show the project's Environment Agent config and recent runs."""
+    from gatewaysdk.environments import GatewayEnvironmentClient
+
+    client = GatewayEnvironmentClient.from_env(host)
+    result = client.get_agent()
+    typer.echo(json.dumps(result.model_dump(), indent=2))
+
+
+@environment_app.command("agent-trigger")
+def environment_agent_trigger(
+    host: Optional[str] = typer.Option(None, "--host", envvar="GATEWAY_HOST"),
+) -> None:
+    """Enqueue a manual Environment Agent run. Requires a saved config and a secret key."""
+    from gatewaysdk.environments import GatewayEnvironmentClient
+
+    client = GatewayEnvironmentClient.from_env(host)
+    result = client.trigger_agent()
+    typer.echo(json.dumps(result.model_dump(), indent=2))
+
+
+# =============================================================================
+# release commands (the CI/CD half of Releases)
+# =============================================================================
+
+release_app = typer.Typer(
+    name="release",
+    help="Release gate for agent builds — ask the platform whether a build may ship.",
+    no_args_is_help=True,
+)
+app.add_typer(release_app, name="release")
+
+
+@release_app.command("gate")
+def release_gate(
+    build: Optional[str] = typer.Option(None, "--build", help="Agent build id."),
+    agent: Optional[str] = typer.Option(None, "--agent", help="Agent id (with --version)."),
+    version: Optional[str] = typer.Option(None, "--version", help="Declared build version (with --agent)."),
+    commit: Optional[str] = typer.Option(
+        None, "--commit", help="Commit sha the build was registered from (full, or a 7+ char prefix)."
+    ),
+    wait: bool = typer.Option(False, "--wait", help="Poll until every run attributed to the build is terminal."),
+    timeout: float = typer.Option(
+        1800.0, "--timeout", min=1.0, help="Seconds to wait for runs to settle (with --wait)."
+    ),
+    interval: float = typer.Option(15.0, "--interval", min=1.0, help="Seconds between polls (with --wait)."),
+    as_json: bool = typer.Option(False, "--json", help="Print the endpoint's JSON instead of a table."),
+    host: Optional[str] = typer.Option(None, "--host", envvar="GATEWAY_HOST"),
+    api_key: Optional[str] = typer.Option(None, "--api-key", envvar="GATEWAY_SECRET_KEY"),
+) -> None:
+    """The release gate's verdict on a build, as an exit code CI can branch on.
+
+    Exit codes::
+
+        0  pass      the gate is open on the build's latest run
+        1  blocked   the latest run failed the project's rule (reasons printed)
+        2  untested  no run recorded this build, or its latest run is still going
+
+    The verdict is computed on the server with the same rule the Releases
+    page enforces on Promote and Rollback; this command never re-derives it.
+
+    Examples::
+
+        gateway release gate --commit $GITHUB_SHA --wait
+        gateway release gate --agent checkout-bot --version 2.4.0 --json
+        gateway release gate --build cm1abc... --wait --timeout 900
+    """
+    import os
+
+    from gatewaysdk.cli import release_gate as gate_mod
+    from gatewaysdk.cli.http_client import create_client
+
+    try:
+        query = gate_mod.build_query(build=build, agent=agent, version=version, commit=commit)
+    except gate_mod.GateLookupError as exc:
+        typer.echo(f"Error: {exc}", err=True)
+        raise typer.Exit(2)
+
+    client = create_client(host, api_key)
+
+    def _progress(result: dict) -> None:
+        if as_json:
+            return
+        runs = result.get("evaluatedRuns") or []
+        pending = [r for r in runs if str(r.get("state", "")).upper() not in gate_mod.TERMINAL_STATES]
+        if not runs:
+            typer.echo("waiting: no run has recorded this build yet", err=True)
+        elif pending:
+            typer.echo(f"waiting: {len(pending)} of {len(runs)} run(s) still going", err=True)
+
+    try:
+        if wait:
+            result, settled = gate_mod.wait_for_gate(
+                client, query, timeout_s=timeout, interval_s=interval, on_poll=_progress
+            )
+            if not settled:
+                typer.echo(f"timed out after {timeout:g}s; reporting the latest verdict", err=True)
+        else:
+            result = gate_mod.fetch_gate(client, query)
+    except LookupError as exc:
+        typer.echo(f"Error: {exc}", err=True)
+        raise typer.Exit(2)
+    except httpx.HTTPStatusError as exc:
+        typer.echo(f"Failed (HTTP {exc.response.status_code}): {exc.response.text}", err=True)
+        raise typer.Exit(2)
+
+    typer.echo(gate_mod.render_json(result) if as_json else gate_mod.render_table(result))
+    gate_mod.write_step_summary(result, os.environ.get("GITHUB_STEP_SUMMARY"))
+    raise typer.Exit(gate_mod.exit_code_for(result))
+
+
+def main() -> None:
+    """Entry point for the `gateway` CLI command."""
+    app()
+
+
+if __name__ == "__main__":
+    main()