cogames 0.3.49__py3-none-any.whl → 0.3.64__py3-none-any.whl

cogames/cli/submit.py

@@ -19,48 +19,43 @@ from rich.console import Console
 from cogames.cli.base import console
 from cogames.cli.login import DEFAULT_COGAMES_SERVER
 from cogames.cli.policy import PolicySpec, get_policy_spec
+from metta_alo.rollout import run_single_episode
 
 if TYPE_CHECKING:
     from cogames.cli.client import TournamentServerClient
 
-from mettagrid.policy.loader import initialize_or_load_policy
-from mettagrid.policy.policy_env_interface import PolicyEnvInterface
+from mettagrid.config.mettagrid_config import MettaGridConfig
 from mettagrid.policy.submission import POLICY_SPEC_FILENAME, SubmissionPolicySpec
 
 DEFAULT_SUBMIT_SERVER = "https://api.observatory.softmax-research.net"
 
 
+def results_url_for_season(_server: str, _season: str) -> str:
+    return "https://www.softmax.com/alignmentleague"
+
+
 @dataclass
 class UploadResult:
     policy_version_id: uuid.UUID
     name: str
     version: int
+    pools: list[str] | None = None
 
 
 def validate_paths(paths: list[str], console: Console) -> list[Path]:
-    """Validate that all paths are relative and within CWD.
-
-    Ensures paths don't escape the current working directory using '../'.
-    Returns list of resolved Path objects.
-    """
-    cwd = Path.cwd()
+    """Validate paths are within CWD and return them as relative paths."""
+    cwd = Path.cwd().resolve()
     validated_paths = []
 
     for path_str in paths:
-        path = Path(path_str)
-
-        # Check if path is absolute
-        if path.is_absolute():
-            console.print(f"[red]Error:[/red] Path must be relative: {path_str}")
-            raise ValueError(f"Absolute paths not allowed: {path_str}")
+        raw_path = Path(path_str).expanduser()
 
         # Resolve the path and check it's within CWD
         try:
-            resolved = (cwd / path).resolve()
-            # Check if resolved path is under CWD
-            resolved.relative_to(cwd)
+            resolved = raw_path.resolve() if raw_path.is_absolute() else (cwd / raw_path).resolve()
+            relative = resolved.relative_to(cwd)
         except ValueError:
-            console.print(f"[red]Error:[/red] Path escapes current directory: {path_str}")
+            console.print(f"[red]Error:[/red] Path must be within the current directory: {path_str}")
             raise ValueError(f"Path escapes CWD: {path_str}") from None
 
         # Check if path exists
@@ -68,32 +63,130 @@ def validate_paths(paths: list[str], console: Console) -> list[Path]:
             console.print(f"[red]Error:[/red] Path does not exist: {path_str}")
             raise FileNotFoundError(f"Path not found: {path_str}")
 
-        validated_paths.append(path)
+        validated_paths.append(relative)
 
     return validated_paths
 
 
-def get_latest_cogames_version() -> str:
-    """Get the latest published cogames version."""
-    response = httpx.get("https://pypi.org/pypi/cogames/json")
+def _maybe_resolve_checkpoint_bundle_uri(policy: str) -> tuple[Path, bool] | None:
+    """Return (local_zip_path, cleanup) if policy points to a checkpoint bundle URI."""
+    from mettagrid.policy.prepare_policy_spec import download_policy_spec_from_s3_as_zip
+    from mettagrid.util.uri_resolvers.schemes import parse_uri, resolve_uri
+
+    first = policy.split(",", 1)[0].strip()
+    parsed = parse_uri(first, allow_none=True, default_scheme=None)
+    if parsed is None or parsed.scheme not in {"file", "s3"}:
+        return None
+
+    resolved = resolve_uri(first)
+    if resolved.scheme == "s3":
+        if not resolved.canonical.endswith(".zip"):
+            raise ValueError("S3 policy specs must be .zip bundles.")
+        return download_policy_spec_from_s3_as_zip(resolved.canonical), False
+
+    local_path = resolved.local_path
+    if local_path is None:
+        raise ValueError(f"Cannot resolve local path for URI: {policy}")
+    if not local_path.exists():
+        raise FileNotFoundError(f"Bundle path not found: {local_path}")
+    if local_path.is_dir():
+        return _zip_directory_bundle(local_path), True
+    if local_path.suffix == ".zip":
+        return local_path, False
+    raise ValueError("Checkpoint bundle must be a directory or .zip file.")
+
+
+def _zip_directory_bundle(bundle_dir: Path) -> Path:
+    zip_fd, zip_path = tempfile.mkstemp(suffix=".zip", prefix="cogames_bundle_")
+    os.close(zip_fd)
+
+    with zipfile.ZipFile(zip_path, "w", zipfile.ZIP_DEFLATED) as zipf:
+        for file_path in bundle_dir.rglob("*"):
+            if file_path.is_file():
+                zipf.write(file_path, arcname=file_path.relative_to(bundle_dir))
+
+    return Path(zip_path)
+
+
+def validate_bundle_in_isolation(policy_zip: Path, console: Console, *, season: str, server: str) -> bool:
+    console.print("[dim]Testing policy bundle can run 10 steps...[/dim]")
+
+    temp_dir = None
+    try:
+        temp_dir = create_temp_validation_env()
+        bundle_name = policy_zip.name
+        shutil.copy2(policy_zip, temp_dir / bundle_name)
+
+        env = os.environ.copy()
+        env["UV_NO_CACHE"] = "1"
+
+        res = subprocess.run(
+            [
+                "uv",
+                "run",
+                "cogames",
+                "validate-policy",
+                "--season",
+                season,
+                "--server",
+                server,
+                "--policy",
+                f"file://./{bundle_name}",
+            ],
+            cwd=temp_dir,
+            capture_output=True,
+            text=True,
+            timeout=300,
+            env=env,
+        )
+        if res.returncode != 0:
+            console.print("[red]Validation failed[/red]")
+            console.print(f"\n[red]Error:[/red]\n{res.stderr}")
+            if res.stdout:
+                console.print(f"\n[dim]Output:[/dim]\n{res.stdout}")
+            return False
+
+        console.print("[green]Validation passed[/green]")
+        return True
+    except subprocess.TimeoutExpired:
+        console.print("[red]Validation timed out after 5 minutes[/red]")
+        return False
+    finally:
+        if temp_dir and temp_dir.exists():
+            shutil.rmtree(temp_dir)
+
+
+def get_latest_pypi_version(package: str) -> str:
+    """Get the latest published version of a package from PyPI."""
+    response = httpx.get(f"https://pypi.org/pypi/{package}/json")
     response.raise_for_status()
     return response.json()["info"]["version"]
 
 
+def get_pypi_requires_python(package: str) -> str:
+    """Get the requires_python constraint from PyPI."""
+    response = httpx.get(f"https://pypi.org/pypi/{package}/json")
+    response.raise_for_status()
+    return response.json()["info"]["requires_python"]
+
+
 def create_temp_validation_env() -> Path:
     """Create a temporary directory with a minimal pyproject.toml.
 
-    The pyproject.toml depends on the latest published cogames package.
+    The pyproject.toml depends on the latest published cogames and cogames-agents packages.
+    Python version is constrained to match mettagrid's published wheels.
     """
     temp_dir = Path(tempfile.mkdtemp(prefix="cogames_submit_"))
 
-    latest_cogames_version = get_latest_cogames_version()
+    latest_cogames_version = get_latest_pypi_version("cogames")
+    latest_agents_version = get_latest_pypi_version("cogames-agents")
+    mettagrid_requires_python = get_pypi_requires_python("mettagrid")
 
     pyproject_content = f"""[project]
 name = "cogames-submission-validator"
 version = "0.1.0"
-requires-python = ">=3.12"
-dependencies = ["cogames=={latest_cogames_version}"]
+requires-python = "{mettagrid_requires_python}"
+dependencies = ["cogames=={latest_cogames_version}", "cogames-agents=={latest_agents_version}"]
 
 [build-system]
 requires = ["setuptools>=42"]
@@ -121,26 +214,27 @@ def copy_files_maintaining_structure(files: list[Path], dest_dir: Path) -> None:
             shutil.copy2(file_path, dest_path)
 
 
-def validate_policy_spec(policy_spec: PolicySpec) -> None:
-    """Validate policy works.
-
-    Loads the policy and runs a single episode (up to 10 steps) using the same
-    multi_episode_rollout flow as `cogames eval`.
-    """
-    from cogames.cli.mission import get_mission
-    from mettagrid.simulator.multi_episode.rollout import multi_episode_rollout
-
-    _, env_cfg, _ = get_mission("machina_1")
-    policy_env_info = PolicyEnvInterface.from_mg_cfg(env_cfg)
-    policy = initialize_or_load_policy(policy_env_info, policy_spec)
-
-    # Run 1 episode for up to 10 steps to validate the policy works
+def validate_policy_spec(policy_spec: PolicySpec, env_cfg: MettaGridConfig) -> None:
+    env_cfg = env_cfg.model_copy()
     env_cfg.game.max_steps = 10
-    multi_episode_rollout(
-        env_cfg=env_cfg,
-        policies=[policy],
-        episodes=1,
+    n = env_cfg.game.num_agents
+    n_submitted = min(2, n)
+    noop_spec = PolicySpec(class_path="mettagrid.policy.noop.NoopPolicy")
+    if n_submitted < n:
+        policy_specs = [policy_spec, noop_spec]
+        assignments = [0] * n_submitted + [1] * (n - n_submitted)
+    else:
+        policy_specs = [policy_spec]
+        assignments = [0] * n
+    run_single_episode(
+        policy_specs=policy_specs,
+        assignments=assignments,
+        env=env_cfg,
+        results_uri=None,
+        replay_uri=None,
         seed=42,
+        max_action_time_ms=10000,
+        device="cpu",
     )
 
 
@@ -149,15 +243,10 @@ def validate_policy_in_isolation(
     include_files: list[Path],
     console: Console,
     setup_script: str | None = None,
+    *,
+    season: str,
+    server: str,
 ) -> bool:
-    """Validate policy works in isolated environment.
-
-    Creates a temp environment with published cogames package,
-    copies include-files, and runs cogames eval for 1 episode with max 10 steps.
-
-    Returns True if validation succeeds, False otherwise.
-    """
-
     def _format_policy_arg(spec: PolicySpec) -> str:
         parts = [f"class={spec.class_path}"]
         if spec.data_path:
@@ -166,7 +255,7 @@ def validate_policy_in_isolation(
             parts.append(f"kw.{key}={value}")
         return ",".join(parts)
 
-    console.print("[dim]Testing policy can run 10 steps on machina_1...[/dim]")
+    console.print("[dim]Testing policy can run 10 steps...[/dim]")
 
     temp_dir = None
     try:
@@ -175,7 +264,7 @@ def validate_policy_in_isolation(
 
         policy_arg = _format_policy_arg(policy_spec)
 
-        def _run_from_tmp_dir(cmd: list[str]) -> subprocess.CompletedProcess:
+        def _run_from_tmp_dir(cmd: list[str]) -> subprocess.CompletedProcess[str]:
             env = os.environ.copy()
             env["UV_NO_CACHE"] = "1"
             res = subprocess.run(
@@ -183,7 +272,7 @@ def validate_policy_in_isolation(
                 cwd=temp_dir,
                 capture_output=True,
                 text=True,
-                timeout=300,  # 5 minute timeout
+                timeout=300,
                 env=env,
             )
             if not res.returncode == 0:
@@ -202,9 +291,14 @@ def validate_policy_in_isolation(
             "cogames",
             "validate-policy",
             policy_arg,
+            "--season",
+            season,
+            "--server",
+            server,
         ]
         if setup_script:
             validate_cmd.extend(["--setup-script", setup_script])
+        validate_cmd.extend(["--policy", policy_arg])
 
         _run_from_tmp_dir(validate_cmd)
 
@@ -261,6 +355,7 @@ def upload_submission(
     zip_path: Path,
     submission_name: str,
     console: Console,
+    season: str | None = None,
 ) -> UploadResult | None:
     """Upload submission to CoGames backend using a presigned S3 URL."""
     console.print("[bold]Uploading[/bold]")
@@ -306,19 +401,24 @@ def upload_submission(
         console.print(f"[red]Upload error: {e}[/red]")
         return None
 
-    console.print("[dim]Registering policy...[/dim]")
+    if not season:
+        console.print("[dim]Uploading policy...[/dim]")
+    else:
+        console.print(f"[dim]Uploading policy and submitting to season {season}...[/dim]")
 
     try:
-        result = client.complete_policy_upload(upload_id, submission_name)
+        result = client.complete_policy_upload(upload_id, submission_name, season=season)
         submission_id = result.get("id")
         name = result.get("name")
         version = result.get("version")
+        pools = result.get("pools")
         if submission_id is not None and name is not None and version is not None:
             try:
                 return UploadResult(
                     policy_version_id=uuid.UUID(str(submission_id)),
                     name=name,
                     version=version,
+                    pools=pools,
                 )
             except ValueError:
                 console.print(f"[red]Invalid submission ID returned: {submission_id}[/red]")
@@ -338,6 +438,55 @@ def upload_submission(
         return None
 
 
+def _upload_policy_bundle(
+    bundle_result: tuple[Path, bool],
+    *,
+    client: TournamentServerClient,
+    name: str,
+    console: Console,
+    init_kwargs: dict[str, str] | None,
+    include_files: list[str] | None,
+    setup_script: str | None,
+    skip_validation: bool,
+    dry_run: bool,
+    validation_season: str,
+    server: str,
+    season: str | None = None,
+) -> UploadResult | None:
+    bundle_zip, cleanup_bundle_zip = bundle_result
+
+    try:
+        if init_kwargs or include_files or setup_script:
+            console.print("[red]Error:[/red] Extra files/kwargs are not supported when uploading a bundle URI.")
+            console.print(
+                "Upload the bundle as-is, or use a short policy name or URI with local files to "
+                "build a new submission zip."
+            )
+            return None
+
+        if not skip_validation:
+            if not validate_bundle_in_isolation(bundle_zip, console, season=validation_season, server=server):
+                console.print("\n[red]Upload aborted due to validation failure.[/red]")
+                return None
+        else:
+            console.print("[dim]Skipping validation[/dim]")
+
+        if dry_run:
+            console.print("[green]Dry run complete[/green]")
+            return None
+
+        with client:
+            result = upload_submission(client, bundle_zip, name, console, season=season)
+        if not result:
+            console.print("\n[red]Upload failed.[/red]")
+            return None
+
+        return result
+    finally:
+        if cleanup_bundle_zip and bundle_zip.exists():
+            bundle_zip.unlink()
+
+
 def upload_policy(
     ctx: typer.Context,
     policy: str,
@@ -349,12 +498,9 @@ def upload_policy(
     dry_run: bool = False,
     skip_validation: bool = False,
     setup_script: str | None = None,
+    validation_season: str = "",
+    season: str | None = None,
 ) -> UploadResult | None:
-    """Upload a policy to CoGames (without submitting to a tournament).
-
-    Returns UploadResult with policy_version_id, name, and version on success.
-    Returns None on failure.
-    """
     from cogames.cli.client import TournamentServerClient
 
     if dry_run:
@@ -364,6 +510,28 @@ def upload_policy(
     if not client:
         return None
 
+    try:
+        bundle_result = _maybe_resolve_checkpoint_bundle_uri(policy)
+    except Exception as e:
+        console.print(f"[red]Error resolving checkpoint bundle:[/red] {e}")
+        return None
+
+    if bundle_result is not None:
+        return _upload_policy_bundle(
+            bundle_result,
+            client=client,
+            name=name,
+            console=console,
+            init_kwargs=init_kwargs,
+            include_files=include_files,
+            setup_script=setup_script,
+            skip_validation=skip_validation,
+            dry_run=dry_run,
+            validation_season=validation_season,
+            server=server,
+            season=season,
+        )
+
     try:
         policy_spec = get_policy_spec(ctx, policy)
     except Exception as e:
@@ -378,11 +546,36 @@ def upload_policy(
             init_kwargs=merged_kwargs,
         )
 
+    cwd = Path.cwd().resolve()
+    if policy_spec.data_path:
+        try:
+            resolved = Path(policy_spec.data_path).expanduser().resolve()
+            data_rel = str(resolved.relative_to(cwd))
+        except ValueError:
+            console.print("[red]Error:[/red] Policy weights path must be within the current directory.")
+            console.print(f"[dim]{policy_spec.data_path}[/dim]")
+            return None
+        policy_spec = PolicySpec(
+            class_path=policy_spec.class_path,
+            data_path=data_rel,
+            init_kwargs=policy_spec.init_kwargs,
+        )
+
+    setup_script_rel: str | None = None
+    if setup_script:
+        try:
+            resolved = Path(setup_script).expanduser().resolve()
+            setup_script_rel = str(resolved.relative_to(cwd))
+        except ValueError:
+            console.print("[red]Error:[/red] Setup script path must be within the current directory.")
+            console.print(f"[dim]{setup_script}[/dim]")
+            return None
+
     files_to_include = []
     if policy_spec.data_path:
         files_to_include.append(policy_spec.data_path)
-    if setup_script:
-        files_to_include.append(setup_script)
+    if setup_script_rel:
+        files_to_include.append(setup_script_rel)
     if include_files:
         files_to_include.extend(include_files)
 
@@ -394,14 +587,21 @@ def upload_policy(
             return None
 
     if not skip_validation:
-        if not validate_policy_in_isolation(policy_spec, validated_paths, console, setup_script=setup_script):
+        if not validate_policy_in_isolation(
+            policy_spec,
+            validated_paths,
+            console,
+            setup_script=setup_script_rel,
+            season=validation_season,
+            server=server,
+        ):
             console.print("\n[red]Upload aborted due to validation failure.[/red]")
             return None
     else:
         console.print("[dim]Skipping validation[/dim]")
 
     try:
-        zip_path = create_submission_zip(validated_paths, policy_spec, setup_script=setup_script)
+        zip_path = create_submission_zip(validated_paths, policy_spec, setup_script=setup_script_rel)
     except Exception as e:
         console.print(f"[red]Error creating zip:[/red] {e}")
         return None
@@ -414,10 +614,11 @@ def upload_policy(
 
     try:
         with client:
-            result = upload_submission(client, zip_path, name, console)
+            result = upload_submission(client, zip_path, name, console, season=season)
         if not result:
             console.print("\n[red]Upload failed.[/red]")
             return None
+
         return result
     finally:
         if zip_path.exists():

cogames/cogs_vs_clips/cog.py

@@ -0,0 +1,79 @@
+from __future__ import annotations
+
+from pydantic import Field
+
+from mettagrid.base_config import Config
+from mettagrid.config.handler_config import Handler
+from mettagrid.config.mettagrid_config import (
+    AgentConfig,
+    InventoryConfig,
+    ResourceLimitsConfig,
+)
+from mettagrid.config.mutation.resource_mutation import updateActor
+
+
+class CogConfig(Config):
+    """Configuration for cog agents in CogsGuard game mode."""
+
+    # Inventory limits
+    gear_limit: int = Field(default=1)
+    hp_limit: int = Field(default=100)
+    heart_limit: int = Field(default=10)
+    energy_limit: int = Field(default=20)
+    cargo_limit: int = Field(default=4)
+    influence_limit: int = Field(default=0)
+
+    # Inventory modifiers by gear type
+    hp_modifiers: dict[str, int] = Field(default_factory=lambda: {"scout": 400, "scrambler": 200})
+    energy_modifiers: dict[str, int] = Field(default_factory=lambda: {"scout": 100})
+    cargo_modifiers: dict[str, int] = Field(default_factory=lambda: {"miner": 40})
+    influence_modifiers: dict[str, int] = Field(default_factory=lambda: {"aligner": 20})
+
+    # Initial inventory
+    initial_energy: int = Field(default=100)
+    initial_hp: int = Field(default=50)
+
+    # Regen amounts
+    energy_regen: int = Field(default=1)
+    hp_regen: int = Field(default=-1)
+    influence_regen: int = Field(default=-1)
+
+    # Movement cost
+    move_energy_cost: int = Field(default=3)
+
+    def agent_config(self, gear: list[str], elements: list[str]) -> AgentConfig:
+        """Create an AgentConfig for this cog configuration."""
+        return AgentConfig(
+            collective="cogs",
+            inventory=InventoryConfig(
+                limits={
+                    "hp": ResourceLimitsConfig(min=self.hp_limit, resources=["hp"], modifiers=self.hp_modifiers),
+                    # when hp == 0, the cog can't hold gear or hearts
+                    "gear": ResourceLimitsConfig(max=self.gear_limit, resources=gear, modifiers={"hp": 100}),
+                    "heart": ResourceLimitsConfig(max=self.heart_limit, resources=["heart"], modifiers={"hp": 100}),
+                    "energy": ResourceLimitsConfig(
+                        min=self.energy_limit, resources=["energy"], modifiers=self.energy_modifiers
+                    ),
+                    "cargo": ResourceLimitsConfig(
+                        min=self.cargo_limit, resources=elements, modifiers=self.cargo_modifiers
+                    ),
+                    "influence": ResourceLimitsConfig(
+                        min=self.influence_limit, resources=["influence"], modifiers=self.influence_modifiers
+                    ),
+                },
+                initial={"energy": self.initial_energy, "hp": self.initial_hp},
+            ),
+            on_tick={
+                "regen": Handler(
+                    mutations=[
+                        updateActor(
+                            {
+                                "energy": self.energy_regen,
+                                "hp": self.hp_regen,
+                                "influence": self.influence_regen,
+                            }
+                        )
+                    ]
+                )
+            },
+        )

cogames/cogs_vs_clips/cogs_vs_clips_mapgen.md

@@ -23,7 +23,7 @@ This guide explains how the procedural map system is wired together and how to e
   - CLI glue (`cogames play`, `cogames missions`, `cogames train`) and variant composition
 
 Everything ultimately produces a `MapBuilderConfig` that feeds into a `MettaGridConfig`. Missions and variants
-coordinate map building, agent setup, and post-processing such as assembler rewrites.
+coordinate map building, agent setup, and post-processing such as hub rewrites.
 
 ---
 
@@ -75,7 +75,7 @@ MACHINA_PROCEDURAL_200 = Site(
             hub_cross_distance=7,
             building_names=[
                 "chest",
-                "charger",
+                "junction",
                 "carbon_extractor",
                 "oxygen_extractor",
                 "germanium_extractor",
@@ -83,7 +83,7 @@ MACHINA_PROCEDURAL_200 = Site(
             ],
             building_weights={
                 "chest": 0.2,
-                "charger": 0.6,
+                "junction": 0.6,
                 "carbon_extractor": 0.3,
                 "oxygen_extractor": 0.3,
                 "germanium_extractor": 0.3,
@@ -93,7 +93,7 @@ MACHINA_PROCEDURAL_200 = Site(
             distribution={"type": "bimodal", "cluster_std": 0.15},
             building_distributions={
                 "chest": {"type": "exponential", "decay_rate": 5.0, "origin_x": 0.0, "origin_y": 0.0},
-                "charger": {"type": "poisson"},
+                "junction": {"type": "poisson"},
             },
         ),
     ),
@@ -208,7 +208,7 @@ Common patterns:
   class MyVariant(MissionVariant):
       name: str = "my"
       def modify_env(self, mission: Mission, env: MettaGridConfig) -> None:
-          env.game.charger.efficiency -= 50
+          env.game.junction.efficiency -= 50
   ```
 
 CLI variants are composed in order, so `cogames play -m machina_procedural.open_world -v city -v both_base` applies
@@ -218,13 +218,16 @@ CLI variants are composed in order, so `cogames play -m machina_procedural.open_
 
 ### Seeds and Reproducibility
 
-- `MapGen.Config.seed` (`env.game.map_builder.seed`) controls **map layout**: set it for deterministic terrain/building
-  placement for a mission/site.
-- `cogames evaluate` and `cogames play` use `--seed` for the simulator/policy RNG and `--map-seed` (or `--seed` if
-  omitted) for `MapGenConfig.seed`, so runs can be made fully reproducible from the CLI.
-- `cogames train` treats `--map-seed` as an **opt-in** override: when set, all procedural training missions use that
-  fixed `MapGenConfig.seed`; when left `None`, the vectorized env factory derives per-env map seeds from the runner’s
-  RNG so a fixed `--seed` yields a reproducible but diverse map sequence.
+- `MapGen.Config.seed` (`env.game.map_builder.seed`) controls **map layout**.
+- If the mission sets a MapGen seed, all commands use it unless you pass `--map-seed`.
+- `--map-seed` overrides the MapGen seed for procedural maps.
+- `--seed` sets the simulator/policy RNG for the run (sim dynamics, policy sampling, assignment shuffles).
+- When a MapGen seed is set (`--map-seed` or mission seed), the map layout follows a deterministic per-episode seed
+  sequence. If `maps_cache_size` is set, the sequence repeats every `maps_cache_size` episodes; otherwise it increases
+  monotonically.
+- When no MapGen seed is set, the map layout is random. With caching enabled, you see up to `maps_cache_size` distinct
+  layouts; with caching disabled (`maps_cache_size=None`), you get a fresh layout each episode.
+- For fully reproducible play/eval runs, set **both** `--seed` and `--map-seed`.
 
 Example programmatic override using the shared `MapSeedVariant` helper:
 
@@ -292,11 +295,11 @@ mission = Mission(
       --seed 12345
   ```
 
-- Reproduce a procedural seed:
+- Reproduce a procedural layout:
   ```bash
-  cogames play -m machina_procedural.open_world --variant city --seed 24601
+  cogames play -m machina_procedural.open_world --variant city --map-seed 24601 --seed 24601
   ```
-  (Assuming the mission/variant combination sets or respects `procedural_overrides["seed"]`.)
+  (Use `--map-seed` for layout determinism; include `--seed` to reproduce simulator/policy RNG.)
 
 ---
 
@@ -340,7 +343,7 @@ Usage example:
 
 ```bash
 uv run python packages/cogames/scripts/run_evaluation.py \
-  --agent cogames.policy.nim_agents.agents.ThinkyAgentsMultiPolicy \
+  --policy thinky \
   --mission-set integrated_evals \
   --cogs 4 \
   --repeats 2