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

cogames/main.py

@@ -18,7 +18,7 @@ import sys
 import threading
 import time
 from pathlib import Path
-from typing import Any, Literal, Optional, TypeVar
+from typing import Literal, Optional, TypeVar
 
 import typer
 import yaml  # type: ignore[import]
@@ -29,14 +29,16 @@ from rich.panel import Panel
 from rich.prompt import Prompt
 from rich.table import Table
 
-import cogames.policy.scripted_agent.starter_agent as starter_agent
+import cogames.policy.starter_agent as starter_agent
 import cogames.policy.trainable_policy_template as trainable_policy_template
 from cogames import evaluate as evaluate_module
 from cogames import game, verbose
+from cogames import pickup as pickup_module
 from cogames import play as play_module
 from cogames import train as train_module
 from cogames.cli.base import console
-from cogames.cli.client import TournamentServerClient
+from cogames.cli.client import SeasonInfo, TournamentServerClient, fetch_default_season, fetch_season_info
+from cogames.cli.docsync import docsync
 from cogames.cli.leaderboard import (
     leaderboard_cmd,
     parse_policy_identifier,
@@ -53,14 +55,17 @@ from cogames.cli.mission import (
     list_variants,
 )
 from cogames.cli.policy import (
+    _translate_error,
     get_policy_spec,
     get_policy_specs_with_proportions,
+    parse_policy_spec,
     policy_arg_example,
     policy_arg_w_proportion_example,
 )
-from cogames.cli.submit import DEFAULT_SUBMIT_SERVER, upload_policy, validate_policy_spec
+from cogames.cli.submit import DEFAULT_SUBMIT_SERVER, results_url_for_season, upload_policy, validate_policy_spec
 from cogames.curricula import make_rotation
 from cogames.device import resolve_training_device
+from mettagrid.config.mettagrid_config import MettaGridConfig
 from mettagrid.mapgen.mapgen import MapGen
 from mettagrid.policy.loader import discover_and_register_policies
 from mettagrid.policy.policy_registry import get_policy_registry
@@ -100,13 +105,21 @@ def _resolve_mettascope_script() -> Path:
     )
 
 
+def _register_policies() -> None:
+    discover_and_register_policies()
+
+
+def _register_policies_callback() -> None:
+    _register_policies()
+
+
 app = typer.Typer(
     help="CoGames - Multi-agent cooperative and competitive games",
     context_settings={"help_option_names": ["-h", "--help"]},
     no_args_is_help=True,
     rich_markup_mode="rich",
     pretty_exceptions_show_locals=False,
-    callback=lambda: discover_and_register_policies("cogames.policy"),
+    callback=_register_policies_callback,
 )
 
 tutorial_app = typer.Typer(
@@ -119,8 +132,12 @@ tutorial_app = typer.Typer(
 if register_tribal_cli is not None:
     register_tribal_cli(app)
 
+app.add_typer(docsync.app, name="docsync", hidden=True)
 
-@tutorial_app.command(name="play", help="Interactive tutorial - learn to play Cogs vs Clips")
+
+@tutorial_app.command(
+    name="play", help="Interactive tutorial - learn to play Cogs vs Clips", rich_help_panel="Tutorial"
+)
 def tutorial_cmd(
     ctx: typer.Context,
 ) -> None:
@@ -130,8 +147,8 @@ def tutorial_cmd(
 
     console.print(
         Panel.fit(
-            "[bold cyan]MISSION BRIEFING: Tutorial Sector[/bold cyan]\n\n"
-            "Welcome, Cognitive. This simulation mirrors frontline HEART ops.\n"
+            "[bold cyan]MISSION BRIEFING: CogsGuard Training Sector[/bold cyan]\n\n"
+            "Welcome, Cognitive. This simulation mirrors frontline CogsGuard ops.\n"
             "We will launch the Mettascope visual interface now.\n\n"
             "When you are ready to deploy, press Enter below and then return here to receive instructions.",
             title="Mission Briefing",
@@ -142,13 +159,11 @@ def tutorial_cmd(
     Prompt.ask("[dim]Press Enter to launch simulation[/dim]", default="", show_default=False)
     console.print("[dim]Initializing Mettascope...[/dim]")
 
-    # Load tutorial mission
-    from cogames.cogs_vs_clips.tutorial_missions import TutorialMission
+    # Load tutorial mission (CogsGuard)
+    from cogames.cogs_vs_clips.missions import make_cogsguard_mission
 
     # Create environment config
-    env_cfg = TutorialMission.make_env()
-    # Force 1 agent for tutorial
-    env_cfg.game.num_agents = 1
+    env_cfg = make_cogsguard_mission(num_agents=1, max_steps=1000).make_env()
 
     stop_event = threading.Event()
 
@@ -174,7 +189,7 @@ def tutorial_cmd(
                     "Right Pane (Vibe Deck): Select icons here to change your Cog's broadcast resonance.",
                     "Zoom/Pan: Scroll or pinch to zoom the arena; drag to pan.",
                     "Click various buildings to view their details in the Left Pane.",
-                    "Look for the Chest, Assembler, Charger, and Extractor stations.",
+                    "Look for the Hub (Hub), Junctions, Gear Stations, and Extractors.",
                     "Click your Cog to assume control.",
                 ),
             },
@@ -182,46 +197,46 @@ def tutorial_cmd(
                 "title": "Step 2 — Movement & Energy",
                 "lines": (
                     "Use WASD or Arrow Keys to move your Cog.",
-                    "Every move costs Energy, every time step recovers Energy.",
+                    "Every move costs Energy, and aligned hubs/junctions recharge you.",
                     "Watch your battery bar on the Cog or in the HUD.",
-                    "If low, rest (skip turn), lean against a wall (walk into it), vibe, or",
-                    "find a Charger [yellow]+[/yellow].",
+                    "If low, rest (skip turn), lean against a wall (walk into it), or",
+                    "stand near the Hub or an aligned Junction.",
                 ),
             },
             {
-                "title": "Step 3 — Extraction",
+                "title": "Step 3 — Gear Up",
                 "lines": (
                     "Primary interaction mode is WALKING INTO things.",
-                    "Locate an Extractor station:",
-                    "  [yellow]C[/yellow] (Carbon), [yellow]O[/yellow] (Oxygen),",
-                    "  [yellow]G[/yellow] (Germanium), [yellow]S[/yellow] (Silicon).",
-                    "Walk into it to extract resources.",
-                    "Note: Silicon ([yellow]S[/yellow]) costs 20 energy!",
+                    "Locate a Gear Station and walk into it to equip a role:",
+                    "  [yellow]⛏ Miner[/yellow], [yellow]🔭 Scout[/yellow],",
+                    "  [yellow]🔗 Aligner[/yellow], [yellow]🌀 Scrambler[/yellow].",
+                    "Gear costs are paid from the team commons.",
                 ),
             },
             {
-                "title": "Step 4 — Crafting (Assembler)",
+                "title": "Step 4 — Resources & Hearts",
                 "lines": (
-                    "Click the central Assembler [yellow]&[/yellow] to see the HEART recipe in the Left Pane.",
-                    "Set your Vibe (Right Pane) to match the requirement (usually [red]heart_a[/red]).",
-                    "Walk into the Assembler to craft. Inputs are taken from your inventory instantly.",
+                    "Find an Extractor station to gather elements:",
+                    "  [yellow]C[/yellow] (Carbon), [yellow]O[/yellow] (Oxygen),",
+                    "  [yellow]G[/yellow] (Germanium), [yellow]S[/yellow] (Silicon).",
+                    "Visit the Chest to assemble or withdraw Hearts from the commons.",
                 ),
             },
             {
-                "title": "Step 5 — Deposit (Chest)",
+                "title": "Step 5 — Junction Control",
                 "lines": (
-                    "Go to the Chest [yellow]C[/yellow] (usually near the center).",
-                    "Switch your Vibe to [red]heart_b[/red] (Deposit Mode).",
-                    "Walk into the Chest to deposit the HEART and complete the objective.",
-                    "Note: To pull resources out of the Chest, you must vibe the matching resource *_a protocol.",
+                    "Junctions (junctions) can be aligned to your team.",
+                    "As an Aligner: get Influence (stand near the Hub) + a Heart, then bump a neutral junction.",
+                    "As a Scrambler: get a Heart, then bump an enemy-aligned junction to neutralize it.",
+                    "Aligned junctions recharge energy for your team.",
                 ),
             },
             {
                 "title": "Step 6 — Objective Complete",
                 "lines": (
                     "[bold green]🎉 Congratulations![/bold green] You have completed the tutorial.",
-                    "You've mastered extraction, crafting, and resource management.",
-                    "[bold cyan]You're now ready to tackle the full mission![/bold cyan]",
+                    "You've mastered movement, gear, resources, and junction control.",
+                    "[bold cyan]You're now ready to tackle the full CogsGuard arena![/bold cyan]",
                 ),
             },
         )
@@ -241,7 +256,7 @@ def tutorial_cmd(
 
         console.print(
             "[bold green]REFERENCE DOSSIERS[/bold green]\n"
-            "- [link=packages/cogames/MISSION.md]MISSION.md[/link]: Machina VII deployment orders.\n"
+            "- [link=packages/cogames/MISSION.md]MISSION.md[/link]: CogsGuard deployment orders.\n"
             "- [link=packages/cogames/README.md]README.md[/link]: System overview and CLI quick start.\n"
             "- [link=packages/cogames/TECHNICAL_MANUAL.md]TECHNICAL_MANUAL.md[/link]: FACE sensor/command schematics."
         )
@@ -268,40 +283,297 @@ def tutorial_cmd(
         stop_event.set()
 
 
-app.add_typer(tutorial_app, name="tutorial")
+@tutorial_app.command(
+    name="cogsguard",
+    help="Interactive CogsGuard tutorial - learn roles and territory control",
+    rich_help_panel="Tutorial",
+)
+def cogsguard_tutorial_cmd(
+    ctx: typer.Context,
+) -> None:
+    """Run the CogsGuard tutorial."""
+    # Suppress logs during tutorial to keep instructions visible
+    logging.getLogger().setLevel(logging.ERROR)
+
+    console.print(
+        Panel.fit(
+            "[bold cyan]MISSION BRIEFING: CogsGuard Training[/bold cyan]\n\n"
+            "Welcome, Cognitive. This simulation introduces you to CogsGuard operations.\n"
+            "You will learn about specialized gear, resource management, and territory control.\n\n"
+            "When you are ready to deploy, press Enter below and then return here to receive instructions.",
+            title="CogsGuard Briefing",
+            border_style="green",
+        )
+    )
+
+    Prompt.ask("[dim]Press Enter to launch simulation[/dim]", default="", show_default=False)
+    console.print("[dim]Initializing Mettascope...[/dim]")
+
+    # Load CogsGuard tutorial mission
+    from cogames.cogs_vs_clips.cogsguard_tutorial import CogsGuardTutorialMission
+
+    # Create environment config
+    env_cfg = CogsGuardTutorialMission.make_env()
+
+    stop_event = threading.Event()
+
+    def _wait_for_enter(prompt: str) -> bool:
+        if stop_event.is_set():
+            return False
+        try:
+            Prompt.ask(prompt, default="", show_default=False)
+        except (KeyboardInterrupt, EOFError):
+            stop_event.set()
+            return False
+        return True
+
+    def run_cogsguard_tutorial_steps():
+        # Wait a moment for the window to appear
+        time.sleep(3)
+
+        tutorial_steps = (
+            {
+                "title": "Step 1 — Objective & Scoring",
+                "lines": (
+                    "CogsGuard is a territory control game. Your team earns points by holding junctions.",
+                    "[bold]Reward per tick[/bold] = junctions held / max_steps / num_cogs",
+                    "Control more junctions, earn more points. You start in your Hub (center).",
+                ),
+                "task": "Click your Cog to select it, then explore your Hub and familiarize yourself with the area.",
+            },
+            {
+                "title": "Step 2 — The Clips Threat",
+                "lines": (
+                    "[bold red]WARNING:[/bold red] Clips are automated enemies that expand territory!",
+                    "Every ~300 steps, Clips [yellow]scramble[/yellow] nearby Cog junctions to neutral.",
+                    "Every ~300 steps, Clips [yellow]capture[/yellow] nearby neutral junctions.",
+                    "Clips expansion has a 25-cell radius. You must actively defend or be overrun!",
+                ),
+            },
+            {
+                "title": "Step 3 — Territory & Resources",
+                "lines": (
+                    "Junctions and Hubs project effects in a [bold]10-cell radius[/bold]:",
+                    "[green]Friendly territory:[/green] Restores +100 HP, +100 energy, +10 influence per tick.",
+                    "[red]Enemy territory:[/red] Drains -1 HP and -100 influence per tick.",
+                    "[bold]HP:[/bold] Base 100. You lose -1 HP/tick outside friendly territory.",
+                    "  At 0 HP, gear and hearts are [bold red]destroyed[/bold red].",
+                    "[bold]Energy:[/bold] Base 20. Moving costs [yellow]3 energy[/yellow]. Regens +1/tick.",
+                    "[yellow]Key insight:[/yellow] Aligners can't capture in enemy AOE (influence drains too fast).",
+                ),
+                "task": "Walk outside your Hub, watch your HP drain, then return to heal.",
+            },
+            {
+                "title": "Step 4 — Gear Stations",
+                "lines": (
+                    "Equip gear at stations. Each costs 6 collective resources (different mixes):",
+                    "[yellow]Miner[/yellow]: +40 cargo, 10x extraction. Cost: 1C/1O/[bold]3G[/bold]/1S",
+                    "[yellow]Aligner[/yellow]: +20 influence cap, captures territory. Cost: [bold]3C[/bold]/1O/1G/1S",
+                    "[yellow]Scrambler[/yellow]: +200 HP, disrupts enemy junctions. Cost: 1C/[bold]3O[/bold]/1G/1S",
+                    "[yellow]Scout[/yellow]: +400 HP, +100 energy, mobile recon. Cost: 1C/1O/1G/[bold]3S[/bold]",
+                    "Switching gear replaces your current gear (only hold one at a time).",
+                ),
+                "task": "Find a Gear Station in your base and equip Miner gear (walk into it).",
+            },
+            {
+                "title": "Step 5 — Capturing & Scrambling",
+                "lines": (
+                    "[bold]To capture a neutral junction (Aligner only):[/bold]",
+                    "  • Requires: Aligner gear + [yellow]1 heart[/yellow] + [yellow]1 influence[/yellow]",
+                    "  • Must NOT be in enemy AOE (influence would be drained)",
+                    "[bold]To scramble an enemy junction (Scrambler only):[/bold]",
+                    "  • Requires: Scrambler gear + [yellow]1 heart[/yellow]",
+                    "  • Converts enemy junction to neutral (then Aligners can capture it)",
+                ),
+            },
+            {
+                "title": "Step 6 — Resources & Hearts",
+                "lines": (
+                    "[bold]Extractors:[/bold] Walk into them to gather resources (1 per use, 10 with Miner gear).",
+                    "[bold]Deposit:[/bold] Walk into the Hub (center of Hub) to deposit resources.",
+                    "[bold]Hearts:[/bold] At the Chest, convert [yellow]1C + 1O + 1G + 1S[/yellow] into 1 heart.",
+                    "  Hearts are spent to capture/scramble junctions.",
+                    "[bold]Aligning:[/bold] Switch to Aligner gear, then walk into a neutral junction to capture it.",
+                    "Team coordination: Miners gather → deposit → make hearts → Aligners/Scramblers use them.",
+                ),
+                "task": (
+                    "Extract resources (C/O/G/S), deposit at the Hub, craft a heart, "
+                    "then switch to Aligner and capture a junction."
+                ),
+            },
+            {
+                "title": "Step 7 — Tutorial Complete",
+                "lines": (
+                    "[bold green]Congratulations![/bold green] You've completed the CogsGuard tutorial.",
+                    "",
+                    "[bold]Remember the core loop:[/bold]",
+                    "  1. Miners gather resources and deposit at the Hub",
+                    "  2. Convert resources to hearts at the Chest",
+                    "  3. Scramblers neutralize enemy junctions (1 heart each)",
+                    "  4. Aligners capture neutral junctions (1 heart + 1 influence each)",
+                    "  5. Defend against Clips expansion!",
+                    "",
+                    "[bold cyan]You're ready for full CogsGuard missions![/bold cyan]",
+                ),
+            },
+        )
+
+        for idx, step in enumerate(tutorial_steps):
+            if stop_event.is_set():
+                return
+            console.print()
+            console.print(f"[bold cyan]{step['title']}[/bold cyan]")
+            console.print()
+            for line in step["lines"]:
+                console.print(f"  • {line}")
+            # Display task if present
+            if "task" in step:
+                console.print()
+                console.print(f"  [bold yellow]TASK:[/bold yellow] {step['task']}")
+            console.print()
+            if idx < len(tutorial_steps) - 1:
+                console.print("[dim]Press Enter to continue...[/dim]")
+                if not _wait_for_enter(""):
+                    return
+
+        console.print("[dim]CogsGuard tutorial briefing complete. Good luck, Cognitive.[/dim]")
+        console.print("[dim]Close the Mettascope window to exit the tutorial.[/dim]")
+
+    # Start tutorial interaction in a background thread
+    tutorial_thread = threading.Thread(target=run_cogsguard_tutorial_steps, daemon=True)
+    tutorial_thread.start()
+
+    # Run play (blocks main thread)
+    try:
+        play_module.play(
+            console,
+            env_cfg=env_cfg,
+            policy_spec=get_policy_spec(ctx, "class=noop"),
+            game_name="cogsguard_tutorial",
+            render_mode="gui",
+        )
+    except KeyboardInterrupt:
+        logger.info("CogsGuard tutorial interrupted; exiting.")
+    finally:
+        stop_event.set()
+
+
+app.add_typer(tutorial_app, name="tutorial", rich_help_panel="Tutorials")
+
+
+def _help_callback(ctx: typer.Context, value: bool) -> None:
+    """Callback for custom help option."""
+    if value:
+        console.print(ctx.get_help())
+        raise typer.Exit()
+
+
+@app.command(
+    name="missions",
+    help="""List available missions.
+
+This command has three modes:
+
+[bold]1. List sites:[/bold] Run with no arguments to see all available sites.
 
+[bold]2. List missions at a site:[/bold] Pass a site name (e.g., 'cogsguard_machina_1') to see its missions.
 
-@app.command("missions", help="List all available missions, or describe a specific mission")
+[bold]3. Describe a mission:[/bold] Use -m to describe a specific mission. Only in this mode do \
+--cogs, --variant, --format, and --save have any effect.""",
+    rich_help_panel="Missions",
+    epilog="""[dim]Examples:[/dim]
+
+  [cyan]cogames missions[/cyan]                                    List all sites
+
+  [cyan]cogames missions cogsguard_machina_1[/cyan]                     List missions at site
+
+  [cyan]cogames missions -m cogsguard_machina_1.basic[/cyan]           Describe a mission
+
+  [cyan]cogames missions -m arena --format json[/cyan]             Output as JSON""",
+    add_help_option=False,
+)
 @app.command("games", hidden=True)
 @app.command("mission", hidden=True)
 def games_cmd(
     ctx: typer.Context,
-    mission: Optional[str] = typer.Option(None, "--mission", "-m", help="Name of the mission"),
-    cogs: Optional[int] = typer.Option(None, "--cogs", "-c", help="Number of cogs (agents)"),
+    # --- List ---
+    site: Optional[str] = typer.Argument(
+        None,
+        metavar="SITE",
+        help="Filter by site (e.g., cogsguard_machina_1)",
+    ),
+    # --- Describe (requires -m) ---
+    mission: Optional[str] = typer.Option(
+        None,
+        "--mission",
+        "-m",
+        metavar="MISSION",
+        help="Mission to describe",
+        rich_help_panel="Describe",
+    ),
+    cogs: Optional[int] = typer.Option(
+        None,
+        "--cogs",
+        "-c",
+        help="Override agent count (requires -m)",
+        rich_help_panel="Describe",
+    ),
     variant: Optional[list[str]] = typer.Option(  # noqa: B008
         None,
         "--variant",
         "-v",
-        help="Mission variant (can be used multiple times, e.g., --variant solar_flare --variant dark_side)",
+        metavar="VARIANT",
+        help="Apply variant (requires -m, repeatable)",
+        rich_help_panel="Describe",
     ),
     format_: Optional[Literal["yaml", "json"]] = typer.Option(
-        None, "--format", help="Output mission configuration in YAML or JSON."
+        None,
+        "--format",
+        help="Output format (requires -m)",
+        rich_help_panel="Describe",
     ),
     save: Optional[Path] = typer.Option(  # noqa: B008
         None,
         "--save",
         "-s",
-        help="Save mission configuration to file (YAML or JSON)",
+        metavar="PATH",
+        help="Save config to file (requires -m)",
+        rich_help_panel="Describe",
+    ),
+    # --- Debug ---
+    print_cvc_config: bool = typer.Option(
+        False,
+        "--print-cvc-config",
+        help="Print CVC mission config (requires -m)",
+        hidden=True,
+    ),
+    print_mg_config: bool = typer.Option(
+        False,
+        "--print-mg-config",
+        help="Print MettaGrid config (requires -m)",
+        hidden=True,
+    ),
+    # --- Help ---
+    _help: bool = typer.Option(
+        False,
+        "--help",
+        "-h",
+        help="Show this message and exit",
+        is_eager=True,
+        callback=_help_callback,
+        rich_help_panel="Other",
     ),
-    print_cvc_config: bool = typer.Option(False, "--print-cvc-config", help="Print Mission config (CVC config)"),
-    print_mg_config: bool = typer.Option(False, "--print-mg-config", help="Print MettaGridConfig"),
-    site: Optional[str] = typer.Argument(None, help="Site to list missions for (e.g., training_facility)"),
 ) -> None:
     if mission is None:
         list_missions(site)
         return
 
-    resolved_mission, env_cfg, mission_cfg = get_mission_name_and_config(ctx, mission, variant, cogs)
+    try:
+        resolved_mission, env_cfg, mission_cfg = get_mission_name_and_config(ctx, mission, variant, cogs)
+    except typer.Exit as exc:
+        if exc.exit_code != 1:
+            raise
+        return
 
     if print_cvc_config or print_mg_config:
         try:
@@ -338,64 +610,190 @@ def games_cmd(
         raise typer.Exit(1) from exc
 
 
-@app.command("evals", help="List all eval missions")
+@app.command("evals", help="List all eval missions", rich_help_panel="Missions")
 def evals_cmd() -> None:
     list_evals()
 
 
-@app.command("variants", help="List all available mission variants")
+@app.command("variants", help="List all available mission variants", rich_help_panel="Missions")
 def variants_cmd() -> None:
     list_variants()
 
 
-@app.command(name="describe", help="Describe a mission and its configuration")
+@app.command(
+    name="describe",
+    help="Describe a mission and its configuration",
+    rich_help_panel="Missions",
+    epilog="""[dim]Examples:[/dim]
+
+  [cyan]cogames describe hello_world.open_world[/cyan]                Describe mission
+
+  [cyan]cogames describe arena -c 4 -v dark_side[/cyan]               With 4 cogs and variant""",
+    add_help_option=False,
+)
 def describe_cmd(
     ctx: typer.Context,
-    mission: str = typer.Argument(..., help="Mission name (e.g., hello_world.open_world)"),
-    cogs: Optional[int] = typer.Option(None, "--cogs", "-c", help="Number of cogs (agents)"),
+    mission: str = typer.Argument(
+        ...,
+        metavar="MISSION",
+        help="Mission name (e.g., hello_world.open_world)",
+    ),
+    cogs: Optional[int] = typer.Option(
+        None,
+        "--cogs",
+        "-c",
+        help="Number of cogs (agents)",
+        rich_help_panel="Configuration",
+    ),
     variant: Optional[list[str]] = typer.Option(  # noqa: B008
         None,
         "--variant",
         "-v",
-        help="Mission variant (can be used multiple times, e.g., --variant solar_flare --variant dark_side)",
+        metavar="VARIANT",
+        help="Apply variant (repeatable)",
+        rich_help_panel="Configuration",
+    ),
+    _help: bool = typer.Option(
+        False,
+        "--help",
+        "-h",
+        help="Show this message and exit",
+        is_eager=True,
+        callback=_help_callback,
+        rich_help_panel="Other",
     ),
 ) -> None:
     resolved_mission, env_cfg, mission_cfg = get_mission_name_and_config(ctx, mission, variant, cogs)
     describe_mission(resolved_mission, env_cfg, mission_cfg)
 
 
-@app.command(name="play", help="Play a game")
+@app.command(
+    name="play",
+    rich_help_panel="Play",
+    help="""Play a game interactively.
+
+This runs a single episode of the game using the specified policy.
+
+By default, the policy is 'noop', so agents won't move unless manually controlled.
+To see agents move by themselves, use `--policy class=random` or `--policy class=baseline`.
+
+You can manually control the actions of a specific cog by clicking on a cog
+in GUI mode or pressing M in unicode mode and using your arrow or WASD keys.
+Log mode is non-interactive and doesn't support manual control.
+""",
+    epilog="""[dim]Examples:[/dim]
+
+[cyan]cogames play -m cogsguard_machina_1.basic[/cyan]                        Interactive
+
+[cyan]cogames play -m cogsguard_machina_1.basic -p class=random[/cyan]        Random policy
+
+[cyan]cogames play -m cogsguard_machina_1.basic -c 4 -p class=baseline[/cyan] Baseline, 4 cogs
+
+[cyan]cogames play -m cogsguard_machina_1 -r unicode[/cyan]                   Terminal mode""",
+    add_help_option=False,
+)
 def play_cmd(
     ctx: typer.Context,
-    mission: Optional[str] = typer.Option(None, "--mission", "-m", help="Name of the mission"),
-    cogs: Optional[int] = typer.Option(None, "--cogs", "-c", help="Number of cogs (agents)"),
+    # --- Game Setup ---
+    mission: Optional[str] = typer.Option(
+        None,
+        "--mission",
+        "-m",
+        metavar="MISSION",
+        help="Mission to play (run [bold]cogames missions[/bold] to list)",
+        rich_help_panel="Game Setup",
+    ),
     variant: Optional[list[str]] = typer.Option(  # noqa: B008
         None,
         "--variant",
         "-v",
-        help="Mission variant (can be used multiple times, e.g., --variant solar_flare --variant dark_side)",
+        metavar="VARIANT",
+        help="Apply variant modifier (repeatable)",
+        rich_help_panel="Game Setup",
+    ),
+    cogs: Optional[int] = typer.Option(
+        None,
+        "--cogs",
+        "-c",
+        metavar="N",
+        help="Number of cogs/agents",
+        show_default="from mission",
+        rich_help_panel="Game Setup",
+    ),
+    # --- Policy ---
+    policy: str = typer.Option(
+        "class=noop",
+        "--policy",
+        "-p",
+        metavar="POLICY",
+        help="Policy controlling cogs ([bold]noop[/bold], [bold]random[/bold], [bold]lstm[/bold], or path)",
+        rich_help_panel="Policy",
+    ),
+    # --- Simulation ---
+    steps: int = typer.Option(
+        1000,
+        "--steps",
+        "-s",
+        metavar="N",
+        help="Max steps per episode",
+        rich_help_panel="Simulation",
+    ),
+    render: RenderMode = typer.Option(  # noqa: B008
+        "gui",
+        "--render",
+        "-r",
+        help=(
+            "[bold]gui[/bold]=MettaScope, [bold]vibescope[/bold]=VibeScope, "
+            "[bold]unicode[/bold]=terminal, [bold]log[/bold]=metrics only"
+        ),
+        rich_help_panel="Simulation",
+    ),
+    seed: int = typer.Option(
+        42,
+        "--seed",
+        help="RNG seed for reproducibility",
+        rich_help_panel="Simulation",
     ),
-    policy: str = typer.Option("class=noop", "--policy", "-p", help=f"Policy ({policy_arg_example})"),
-    steps: int = typer.Option(1000, "--steps", "-s", help="Number of steps to run", min=1),
-    render: RenderMode = typer.Option("gui", "--render", "-r", help="Render mode"),  # noqa: B008
-    seed: int = typer.Option(42, "--seed", help="Seed for the simulator and policy", min=0),
     map_seed: Optional[int] = typer.Option(
         None,
         "--map-seed",
-        help="Override MapGen seed for procedural maps (defaults to --seed if not set)",
-        min=0,
-    ),
-    print_cvc_config: bool = typer.Option(
-        False, "--print-cvc-config", help="Print Mission config (CVC config) and exit"
+        metavar="SEED",
+        help="Separate seed for procedural map generation",
+        show_default="same as --seed",
+        rich_help_panel="Simulation",
     ),
-    print_mg_config: bool = typer.Option(False, "--print-mg-config", help="Print MettaGridConfig and exit"),
+    # --- Output ---
     save_replay_dir: Optional[Path] = typer.Option(  # noqa: B008
         None,
         "--save-replay-dir",
-        help=(
-            "Directory to save replay. Directory will be created if it doesn't exist. "
-            "Replay will be saved with a unique UUID-based filename."
-        ),
+        metavar="DIR",
+        help="Save replay file for later viewing with [bold]cogames replay[/bold]",
+        rich_help_panel="Output",
+    ),
+    # --- Debug (hidden from casual users) ---
+    print_cvc_config: bool = typer.Option(
+        False,
+        "--print-cvc-config",
+        help="Print mission config and exit",
+        rich_help_panel="Debug",
+        hidden=True,
+    ),
+    print_mg_config: bool = typer.Option(
+        False,
+        "--print-mg-config",
+        help="Print MettaGrid config and exit",
+        rich_help_panel="Debug",
+        hidden=True,
+    ),
+    # --- Help at end ---
+    _help: bool = typer.Option(
+        False,
+        "--help",
+        "-h",
+        help="Show this message and exit",
+        is_eager=True,
+        callback=_help_callback,
+        rich_help_panel="Other",
     ),
 ) -> None:
     resolved_mission, env_cfg, mission_cfg = get_mission_name_and_config(ctx, mission, variant, cogs)
@@ -407,15 +805,11 @@ def play_cmd(
             console.print(f"[red]Error printing config: {exc}[/red]")
             raise typer.Exit(1) from exc
 
-    # Optionally override MapGen seed so maps are reproducible across runs.
-    # This uses --map-seed if provided, otherwise reuses the main --seed.
-    from mettagrid.mapgen.mapgen import MapGen
-
-    effective_map_seed: Optional[int] = map_seed if map_seed is not None else seed
-    if effective_map_seed is not None:
+    # Optional MapGen seed override for procedural maps.
+    if map_seed is not None:
         map_builder = getattr(env_cfg.game, "map_builder", None)
-        if isinstance(map_builder, MapGen.Config) and map_builder.seed is None:
-            map_builder.seed = effective_map_seed
+        if isinstance(map_builder, MapGen.Config):
+            map_builder.seed = map_seed
 
     policy_spec = get_policy_spec(ctx, policy)
     console.print(f"[cyan]Playing {resolved_mission}[/cyan]")
@@ -439,11 +833,32 @@ def play_cmd(
     )
 
 
-@app.command(name="replay", help="Replay a saved game using MettaScope")
+@app.command(
+    name="replay",
+    help="Replay a saved game episode from a file in the GUI",
+    rich_help_panel="Play",
+    epilog="""[dim]Examples:[/dim]
+
+  [cyan]cogames replay ./replays/game.replay[/cyan]              Replay a saved game
+
+  [cyan]cogames replay ./train_dir/my_run/replay.bin[/cyan]      Replay from training run""",
+    add_help_option=False,
+)
 def replay_cmd(
-    replay_path: Path = typer.Argument(..., help="Path to the replay file"),  # noqa: B008
+    replay_path: Path = typer.Argument(  # noqa: B008
+        ...,
+        metavar="FILE",
+        help="Path to the replay file (.replay or .bin)",
+    ),
+    _help: bool = typer.Option(
+        False,
+        "--help",
+        "-h",
+        help="Show this message and exit",
+        is_eager=True,
+        callback=_help_callback,
+    ),
 ) -> None:
-    """Replay a saved game using MettaScope visualization tool."""
     if not replay_path.exists():
         console.print(f"[red]Error: Replay file not found: {replay_path}[/red]")
         raise typer.Exit(1)
@@ -468,15 +883,73 @@ def replay_cmd(
         raise typer.Exit(1) from exc
 
 
-@app.command("make-mission", help="Create a new mission configuration")
+@app.command(
+    name="make-mission",
+    help="Create a custom mission from a base template",
+    rich_help_panel="Missions",
+    epilog="""[dim]Examples:[/dim]
+
+  [cyan]cogames make-mission -m hello_world -c 8 -o my_mission.yml[/cyan]             8 cogs
+
+  [cyan]cogames make-mission -m arena --width 64 --height 64 -o big.yml[/cyan]        64x64 map
+
+  [cyan]cogames play -m my_mission.yml[/cyan]                                         Use custom mission""",
+    add_help_option=False,
+)
 @app.command("make-game", hidden=True)
 def make_mission(
     ctx: typer.Context,
-    base_mission: Optional[str] = typer.Option(None, "--mission", "-m", help="Base mission to start configuring from"),
-    cogs: Optional[int] = typer.Option(None, "--cogs", "-c", help="Number of cogs (agents)", min=1),
-    width: Optional[int] = typer.Option(None, "--width", "-w", help="Map width", min=1),
-    height: Optional[int] = typer.Option(None, "--height", "-h", help="Map height", min=1),
-    output: Optional[Path] = typer.Option(None, "--output", "-o", help="Output file path (yml or json)"),  # noqa: B008
+    # --- Mission ---
+    base_mission: Optional[str] = typer.Option(
+        None,
+        "--mission",
+        "-m",
+        metavar="MISSION",
+        help="Base mission to start from",
+        rich_help_panel="Mission",
+    ),
+    # --- Customization ---
+    cogs: Optional[int] = typer.Option(
+        None,
+        "--cogs",
+        "-c",
+        help="Number of cogs (agents)",
+        min=1,
+        rich_help_panel="Customization",
+    ),
+    width: Optional[int] = typer.Option(
+        None,
+        "--width",
+        help="Map width",
+        min=1,
+        rich_help_panel="Customization",
+    ),
+    height: Optional[int] = typer.Option(
+        None,
+        "--height",
+        help="Map height",
+        min=1,
+        rich_help_panel="Customization",
+    ),
+    # --- Output ---
+    output: Optional[Path] = typer.Option(  # noqa: B008
+        None,
+        "--output",
+        "-o",
+        metavar="PATH",
+        help="Output file path (.yml or .json)",
+        rich_help_panel="Output",
+    ),
+    # --- Help ---
+    _help: bool = typer.Option(
+        False,
+        "--help",
+        "-h",
+        help="Show this message and exit",
+        is_eager=True,
+        callback=_help_callback,
+        rich_help_panel="Other",
+    ),
 ) -> None:
     try:
         resolved_mission, env_cfg, _ = get_mission_name_and_config(ctx, base_mission)
@@ -514,13 +987,52 @@ def make_mission(
         raise typer.Exit(1) from exc
 
 
-@tutorial_app.command("make-policy", help="Create a new policy from a template")
+# TODO (cogsguard migration): Verify make-policy templates work with CogsGuard game mechanics
+@tutorial_app.command(
+    name="make-policy",
+    help="Create a new policy from a template. Requires --trainable or --scripted.",
+    rich_help_panel="Tutorial",
+    epilog="""[dim]Examples:[/dim]
+
+[cyan]cogames tutorial make-policy -t -o my_nn_policy.py[/cyan]        Trainable (neural network)
+
+[cyan]cogames tutorial make-policy -s -o my_scripted_policy.py[/cyan]  Scripted (rule-based)""",
+    add_help_option=False,
+)
 def make_policy(
-    output: Path = typer.Option("my_policy.py", "--output", "-o", help="Output file path"),  # noqa: B008
-    trainable: bool = typer.Option(False, "--trainable", "-t", help="Create a trainable (neural network) policy"),
-    scripted: bool = typer.Option(False, "--scripted", "-s", help="Create a scripted (rule-based) policy"),
+    # --- Policy Type ---
+    trainable: bool = typer.Option(
+        False,
+        "--trainable",
+        help="Create a trainable (neural network) policy",
+        rich_help_panel="Policy Type",
+    ),
+    scripted: bool = typer.Option(
+        False,
+        "--scripted",
+        help="Create a scripted (rule-based) policy",
+        rich_help_panel="Policy Type",
+    ),
+    # --- Output ---
+    output: Path = typer.Option(  # noqa: B008
+        "my_policy.py",
+        "--output",
+        "-o",
+        metavar="FILE",
+        help="Output file path",
+        rich_help_panel="Output",
+    ),
+    # --- Help ---
+    _help: bool = typer.Option(
+        False,
+        "--help",
+        "-h",
+        help="Show this message and exit",
+        is_eager=True,
+        callback=_help_callback,
+        rich_help_panel="Other",
+    ),
 ) -> None:
-    """Create a new policy from a template. Requires either --trainable or --scripted."""
     if trainable == scripted:
         console.print("[red]Error: Specify exactly one of --trainable or --scripted[/red]")
         console.print("[dim]Examples:[/dim]")
@@ -550,14 +1062,20 @@ def make_policy(
         shutil.copy2(template_path, dest_path)
         console.print(f"[green]{policy_type} policy template copied to: {dest_path}[/green]")
 
+        if not trainable:
+            content = dest_path.read_text()
+            lines = content.splitlines()
+            lines = [line for line in lines if not line.strip().startswith("short_names =")]
+            dest_path.write_text("\n".join(lines) + "\n")
+
         if trainable:
             console.print(
-                "[dim]Train with: cogames tutorial train -m training_facility.harvest -p class="
+                "[dim]Train with: cogames tutorial train -m cogsguard_machina_1.basic -p class="
                 f"{dest_path.stem}.{policy_class}[/dim]"
             )
         else:
             console.print(
-                "[dim]Play with: cogames play -m training_facility.harvest -p class="
+                "[dim]Play with: cogames play -m cogsguard_machina_1.basic -p class="
                 f"{dest_path.stem}.{policy_class}[/dim]"
             )
 
@@ -569,57 +1087,179 @@ def make_policy(
 app.command(name="make-policy", hidden=True)(make_policy)
 
 
-@tutorial_app.command(name="train", help="Train a policy on a mission")
+@tutorial_app.command(
+    name="train",
+    help="""Train a policy on one or more missions.
+
+By default, our 'lstm' policy architecture is used. You can select a different architecture
+(like 'stateless' or 'baseline'), or define your own implementing the MultiAgentPolicy
+interface with a trainable network() method (see mettagrid/policy/policy.py).
+
+Continue training from a checkpoint using URI format, or load weights into an explicit class
+with class=...,data=... syntax.
+
+Supply repeated -m flags to create a training curriculum that rotates through missions.
+Use wildcards (*) in mission names to match multiple missions at once.""",
+    rich_help_panel="Tutorial",
+    epilog="""[dim]Examples:[/dim]
+
+[cyan]cogames tutorial train -m cogsguard_machina_1.basic[/cyan]                   Basic training
+
+[cyan]cogames tutorial train -m cogsguard_machina_1.basic -p class=baseline[/cyan]
+                                                                 Train baseline policy
+
+[cyan]cogames tutorial train -p ./train_dir/my_run:v5[/cyan]                  Continue from checkpoint
+
+[cyan]cogames tutorial train -p class=lstm,data=./weights.safetensors[/cyan]  Load weights into class
+
+[cyan]cogames tutorial train -m mission_1 -m mission_2[/cyan]                 Curriculum (rotates)
+
+[dim]Wildcard patterns:[/dim]
+
+[cyan]cogames tutorial train -m 'machina_2_bigger:*'[/cyan]                   All missions on machina_2_bigger
+
+[cyan]cogames tutorial train -m '*:shaped'[/cyan]                             All "shaped" missions
+
+[cyan]cogames tutorial train -m 'machina*:shaped'[/cyan]                      All "shaped" on machina maps""",
+    add_help_option=False,
+)
 def train_cmd(
     ctx: typer.Context,
-    missions: Optional[list[str]] = typer.Option(None, "--mission", "-m", help="Missions to train on"),  # noqa: B008
-    cogs: Optional[int] = typer.Option(None, "--cogs", "-c", help="Number of cogs (agents)"),
+    # --- Mission Setup ---
+    missions: Optional[list[str]] = typer.Option(  # noqa: B008
+        None,
+        "--mission",
+        "-m",
+        metavar="MISSION",
+        help="Missions to train on (wildcards supported, repeatable for curriculum)",
+        rich_help_panel="Mission Setup",
+    ),
+    cogs: Optional[int] = typer.Option(
+        None,
+        "--cogs",
+        "-c",
+        metavar="N",
+        help="Number of cogs (agents)",
+        show_default="from mission",
+        rich_help_panel="Mission Setup",
+    ),
     variant: Optional[list[str]] = typer.Option(  # noqa: B008
         None,
         "--variant",
         "-v",
-        help="Mission variant (can be used multiple times, e.g., --variant solar_flare --variant dark_side)",
+        metavar="VARIANT",
+        help="Mission variant (repeatable)",
+        rich_help_panel="Mission Setup",
     ),
-    policy: str = typer.Option("class=lstm", "--policy", "-p", help=f"Policy ({policy_arg_example})"),
-    checkpoints_path: str = typer.Option(
-        "./train_dir",
-        "--checkpoints",
-        help="Path to save training data",
+    # --- Policy ---
+    policy: str = typer.Option(
+        "class=lstm",
+        "--policy",
+        "-p",
+        metavar="POLICY",
+        help=f"Policy to train ({policy_arg_example})",
+        rich_help_panel="Policy",
     ),
-    steps: int = typer.Option(10_000_000_000, "--steps", "-s", help="Number of training steps", min=1),
-    device: str = typer.Option(
-        "auto",
-        "--device",
-        help="Device to train on (e.g. 'auto', 'cpu', 'cuda')",
+    # --- Training ---
+    steps: int = typer.Option(
+        10_000_000_000,
+        "--steps",
+        metavar="N",
+        help="Number of training steps",
+        min=1,
+        rich_help_panel="Training",
     ),
-    seed: int = typer.Option(42, "--seed", help="Seed for training", min=0),
-    map_seed: Optional[int] = typer.Option(
-        None,
-        "--map-seed",
-        help="Optional MapGen seed override for procedural maps (for deterministic map layouts)",
-        min=0,
+    batch_size: int = typer.Option(
+        4096,
+        "--batch-size",
+        metavar="N",
+        help="Batch size for training",
+        min=1,
+        rich_help_panel="Training",
+    ),
+    minibatch_size: int = typer.Option(
+        4096,
+        "--minibatch-size",
+        metavar="N",
+        help="Minibatch size for training",
+        min=1,
+        rich_help_panel="Training",
+    ),
+    # --- Hardware ---
+    device: str = typer.Option(
+        "cpu",
+        "--device",
+        metavar="DEVICE",
+        help="Device to train on (auto, cpu, cuda, mps)",
+        rich_help_panel="Hardware",
     ),
-    batch_size: int = typer.Option(4096, "--batch-size", help="Batch size for training", min=1),
-    minibatch_size: int = typer.Option(4096, "--minibatch-size", help="Minibatch size for training", min=1),
     num_workers: Optional[int] = typer.Option(
         None,
         "--num-workers",
-        help="Number of worker processes (defaults to number of CPU cores)",
+        metavar="N",
+        help="Number of worker processes",
+        show_default="CPU cores",
         min=1,
+        rich_help_panel="Hardware",
     ),
     parallel_envs: Optional[int] = typer.Option(
         None,
         "--parallel-envs",
+        metavar="N",
         help="Number of parallel environments",
         min=1,
+        rich_help_panel="Hardware",
     ),
     vector_batch_size: Optional[int] = typer.Option(
         None,
         "--vector-batch-size",
-        help="Override vectorized environment batch size",
+        metavar="N",
+        help="Vectorized environment batch size",
         min=1,
+        rich_help_panel="Hardware",
+    ),
+    # --- Reproducibility ---
+    seed: int = typer.Option(
+        42,
+        "--seed",
+        metavar="N",
+        help="Seed for training RNG",
+        min=0,
+        rich_help_panel="Reproducibility",
+    ),
+    map_seed: Optional[int] = typer.Option(
+        None,
+        "--map-seed",
+        metavar="N",
+        help="MapGen seed for procedural map layout",
+        show_default="same as --seed",
+        min=0,
+        rich_help_panel="Reproducibility",
+    ),
+    # --- Output ---
+    checkpoints_path: str = typer.Option(
+        "./train_dir",
+        "--checkpoints",
+        metavar="DIR",
+        help="Path to save training checkpoints",
+        rich_help_panel="Output",
+    ),
+    log_outputs: bool = typer.Option(
+        False,
+        "--log-outputs",
+        help="Log training outputs",
+        rich_help_panel="Output",
+    ),
+    # --- Help ---
+    _help: bool = typer.Option(
+        False,
+        "--help",
+        "-h",
+        help="Show this message and exit",
+        is_eager=True,
+        callback=_help_callback,
+        rich_help_panel="Other",
     ),
-    log_outputs: bool = typer.Option(False, "--log-outputs", help="Log training outputs"),
 ) -> None:
     selected_missions = get_mission_names_and_configs(ctx, missions, variants_arg=variant, cogs=cogs)
     if len(selected_missions) == 1:
@@ -637,29 +1277,6 @@ def train_cmd(
     policy_spec = get_policy_spec(ctx, policy)
     torch_device = resolve_training_device(console, device)
 
-    # Optional MapGen seed override for deterministic procedural maps during training.
-    # We keep this opt-in (via --map-seed) to avoid reducing map diversity by default.
-
-    if map_seed is not None:
-
-        def _maybe_seed(cfg: Any) -> None:
-            mb = getattr(cfg.game, "map_builder", None)
-            if isinstance(mb, MapGen.Config) and mb.seed is None:
-                mb.seed = map_seed
-
-        if env_cfg is not None:
-            _maybe_seed(env_cfg)
-
-        if supplier is not None:
-            base_supplier = supplier
-
-            def _seeded_supplier() -> Any:
-                cfg = base_supplier()
-                _maybe_seed(cfg)
-                return cfg
-
-            supplier = _seeded_supplier
-
     try:
         train_module.train(
             env_cfg=env_cfg,
@@ -669,6 +1286,7 @@ def train_cmd(
             num_steps=steps,
             checkpoints_path=Path(checkpoints_path),
             seed=seed,
+            map_seed=map_seed,
             batch_size=batch_size,
             minibatch_size=minibatch_size,
             vector_num_workers=num_workers,
@@ -691,64 +1309,154 @@ app.command(name="train", hidden=True)(train_cmd)
 
 @app.command(
     name="run",
-    help="Evaluate one or more policies on one or more missions",
+    help="""Evaluate one or more policies on missions.
+
+With multiple policies (e.g., 2 policies, 4 agents), each policy always controls 2 agents,
+but which agents swap between policies each episode.
+
+With one policy, this command is equivalent to `cogames scrimmage`.
+""",
+    rich_help_panel="Evaluate",
+    epilog="""[dim]Examples:[/dim]
+
+[cyan]cogames run -m cogsguard_machina_1.basic -p lstm[/cyan]               Evaluate single policy
+
+[cyan]cogames run -m cogsguard_machina_1 -p ./train_dir/my_run:v5[/cyan]     Evaluate a checkpoint bundle
+
+[cyan]cogames run -S integrated_evals -p ./train_dir/my_run:v5[/cyan]    Evaluate on mission set
+
+[cyan]cogames run -m 'arena.*' -p lstm -p random -e 20[/cyan]            Evaluate multiple policies together
+
+[cyan]cogames run -m cogsguard_machina_1 -p ./train_dir/my_run:v5,proportion=3 -p class=random,proportion=5[/cyan]
+                                                             Evaluate policies in 3:5 mix""",
+    add_help_option=False,
+)
+@app.command(
+    name="scrimmage",
+    help="""Evaluate a single policy controlling all agents.
+
+This command is equivalent to running `cogames run` with a single policy.
+""",
+    rich_help_panel="Evaluate",
+    epilog="""[dim]Examples:[/dim]
+
+[cyan]cogames scrimmage -m arena.battle -p lstm[/cyan]                   Single policy eval""",
+    add_help_option=False,
 )
 @app.command("eval", hidden=True)
 @app.command("evaluate", hidden=True)
 def run_cmd(
     ctx: typer.Context,
+    # --- Mission ---
     missions: Optional[list[str]] = typer.Option(  # noqa: B008
         None,
         "--mission",
         "-m",
-        help="Missions to evaluate (supports wildcards, e.g., --mission training_facility.*)",
+        metavar="MISSION",
+        help="Missions to evaluate (supports wildcards)",
+        rich_help_panel="Mission",
     ),
     mission_set: Optional[str] = typer.Option(
         None,
         "--mission-set",
         "-S",
-        help="Predefined mission set: eval_missions, integrated_evals, spanning_evals, diagnostic_evals, all",
+        metavar="SET",
+        help="Predefined set: integrated_evals, spanning_evals, diagnostic_evals, all",
+        rich_help_panel="Mission",
+    ),
+    cogs: Optional[int] = typer.Option(
+        None,
+        "--cogs",
+        "-c",
+        metavar="N",
+        help="Number of cogs (agents)",
+        rich_help_panel="Mission",
     ),
-    cogs: Optional[int] = typer.Option(None, "--cogs", "-c", help="Number of cogs (agents)"),
     variant: Optional[list[str]] = typer.Option(  # noqa: B008
         None,
         "--variant",
         "-v",
-        help="Mission variant (can be used multiple times, e.g., --variant solar_flare --variant dark_side)",
+        metavar="VARIANT",
+        help="Mission variant (repeatable)",
+        rich_help_panel="Mission",
     ),
+    # --- Policy ---
     policies: Optional[list[str]] = typer.Option(  # noqa: B008
         None,
         "--policy",
         "-p",
+        metavar="POLICY",
         help=f"Policies to evaluate: ({policy_arg_w_proportion_example}...)",
+        rich_help_panel="Policy",
     ),
-    episodes: int = typer.Option(10, "--episodes", "-e", help="Number of evaluation episodes", min=1),
-    action_timeout_ms: int = typer.Option(
-        250,
-        "--action-timeout-ms",
-        help="Max milliseconds afforded to generate each action before noop is used by default",
+    # --- Simulation ---
+    episodes: int = typer.Option(
+        10,
+        "--episodes",
+        "-e",
+        metavar="N",
+        help="Number of evaluation episodes",
+        min=1,
+        rich_help_panel="Simulation",
+    ),
+    steps: Optional[int] = typer.Option(
+        1000,
+        "--steps",
+        "-s",
+        metavar="N",
+        help="Max steps per episode",
         min=1,
+        rich_help_panel="Simulation",
+    ),
+    seed: int = typer.Option(
+        42,
+        "--seed",
+        metavar="N",
+        help="Seed for evaluation RNG",
+        min=0,
+        rich_help_panel="Simulation",
     ),
-    steps: Optional[int] = typer.Option(1000, "--steps", "-s", help="Max steps per episode", min=1),
-    seed: int = typer.Option(42, "--seed", help="Base random seed for evaluation", min=0),
     map_seed: Optional[int] = typer.Option(
         None,
         "--map-seed",
-        help="Override MapGen seed for procedural maps (defaults to --seed if not set)",
+        metavar="N",
+        help="MapGen seed for procedural maps",
         min=0,
+        show_default="same as --seed",
+        rich_help_panel="Simulation",
     ),
+    action_timeout_ms: int = typer.Option(
+        250,
+        "--action-timeout-ms",
+        metavar="MS",
+        help="Max ms per action before noop",
+        min=1,
+        rich_help_panel="Simulation",
+    ),
+    # --- Output ---
     format_: Optional[Literal["yaml", "json"]] = typer.Option(
         None,
         "--format",
-        help="Output results in YAML or JSON format",
+        metavar="FMT",
+        help="Output format: yaml or json",
+        rich_help_panel="Output",
     ),
     save_replay_dir: Optional[Path] = typer.Option(  # noqa: B008
         None,
         "--save-replay-dir",
-        help=(
-            "Directory to save replays. Directory will be created if it doesn't exist. "
-            "Each replay will be saved with a unique UUID-based filename."
-        ),
+        metavar="DIR",
+        help="Directory to save replays",
+        rich_help_panel="Output",
+    ),
+    # --- Help ---
+    _help: bool = typer.Option(
+        False,
+        "--help",
+        "-h",
+        help="Show this message and exit",
+        is_eager=True,
+        callback=_help_callback,
+        rich_help_panel="Other",
     ),
 ) -> None:
     # Handle mission set expansion
@@ -773,19 +1481,23 @@ def run_cmd(
 
     selected_missions = get_mission_names_and_configs(ctx, missions, variants_arg=variant, cogs=cogs, steps=steps)
 
-    # Optionally override MapGen seed so maps are reproducible across runs.
-    # This uses --map-seed if provided, otherwise reuses the main --seed.
-    from mettagrid.mapgen.mapgen import MapGen
-
-    effective_map_seed: Optional[int] = map_seed if map_seed is not None else seed
-    if effective_map_seed is not None:
+    # Optional MapGen seed override for procedural maps.
+    if map_seed is not None:
         for _, env_cfg in selected_missions:
             map_builder = getattr(env_cfg.game, "map_builder", None)
             if isinstance(map_builder, MapGen.Config):
-                map_builder.seed = effective_map_seed
+                map_builder.seed = map_seed
 
     policy_specs = get_policy_specs_with_proportions(ctx, policies)
 
+    if ctx.info_name == "scrimmage":
+        if len(policy_specs) != 1:
+            console.print("[red]Error: scrimmage accepts exactly one --policy / -p value.[/red]")
+            raise typer.Exit(1)
+        if policy_specs[0].proportion != 1.0:
+            console.print("[red]Error: scrimmage does not support policy proportions.[/red]")
+            raise typer.Exit(1)
+
     console.print(
         f"[cyan]Preparing evaluation for {len(policy_specs)} policies across {len(selected_missions)} mission(s)[/cyan]"
     )
@@ -803,7 +1515,170 @@ def run_cmd(
     )
 
 
-@app.command(name="version", help="Show version information")
+@app.command(
+    name="pickup",
+    help="Evaluate a policy against a pool of other policies and compute VOR",
+    rich_help_panel="Evaluate",
+    epilog="""[dim]Examples:[/dim]
+
+[cyan]cogames pickup -p greedy --pool random[/cyan]                      Test greedy against pool of random""",
+    add_help_option=False,
+)
+def pickup_cmd(
+    ctx: typer.Context,
+    # --- Mission ---
+    mission: str = typer.Option(
+        "cogsguard_machina_1.basic",
+        "--mission",
+        "-m",
+        metavar="MISSION",
+        help="Mission to evaluate on",
+        rich_help_panel="Mission",
+    ),
+    cogs: int = typer.Option(
+        4,
+        "--cogs",
+        "-c",
+        metavar="N",
+        help="Number of cogs (agents)",
+        min=1,
+        rich_help_panel="Mission",
+    ),
+    variant: Optional[list[str]] = typer.Option(  # noqa: B008
+        None,
+        "--variant",
+        "-v",
+        metavar="VARIANT",
+        help="Mission variant (repeatable)",
+        rich_help_panel="Mission",
+    ),
+    # --- Policy ---
+    policy: Optional[str] = typer.Option(
+        None,
+        "--policy",
+        "-p",
+        metavar="POLICY",
+        help="Candidate policy to evaluate",
+        rich_help_panel="Policy",
+    ),
+    pool: Optional[list[str]] = typer.Option(  # noqa: B008
+        None,
+        "--pool",
+        metavar="POLICY",
+        help="Pool policy (repeatable)",
+        rich_help_panel="Policy",
+    ),
+    # --- Simulation ---
+    episodes: int = typer.Option(
+        1,
+        "--episodes",
+        "-e",
+        metavar="N",
+        help="Episodes per scenario",
+        min=1,
+        rich_help_panel="Simulation",
+    ),
+    steps: Optional[int] = typer.Option(
+        1000,
+        "--steps",
+        "-s",
+        metavar="N",
+        help="Max steps per episode",
+        min=1,
+        rich_help_panel="Simulation",
+    ),
+    seed: int = typer.Option(
+        50,
+        "--seed",
+        metavar="N",
+        help="Base random seed",
+        min=0,
+        rich_help_panel="Simulation",
+    ),
+    map_seed: Optional[int] = typer.Option(
+        None,
+        "--map-seed",
+        metavar="N",
+        help="MapGen seed for procedural maps",
+        min=0,
+        show_default="same as --seed",
+        rich_help_panel="Simulation",
+    ),
+    action_timeout_ms: int = typer.Option(
+        250,
+        "--action-timeout-ms",
+        metavar="MS",
+        help="Max ms per action before noop",
+        min=1,
+        rich_help_panel="Simulation",
+    ),
+    # --- Output ---
+    save_replay_dir: Optional[Path] = typer.Option(  # noqa: B008
+        None,
+        "--save-replay-dir",
+        metavar="DIR",
+        help="Directory to save replays",
+        rich_help_panel="Output",
+    ),
+    # --- Help ---
+    _help: bool = typer.Option(
+        False,
+        "--help",
+        "-h",
+        help="Show this message and exit",
+        is_eager=True,
+        callback=_help_callback,
+        rich_help_panel="Other",
+    ),
+) -> None:
+    import httpx
+
+    if policy is None:
+        console.print(ctx.get_help())
+        console.print("[yellow]Missing: --policy / -p[/yellow]\n")
+        raise typer.Exit(1)
+
+    if not pool:
+        console.print(ctx.get_help())
+        console.print("[yellow]Supply at least one: --pool[/yellow]\n")
+        raise typer.Exit(1)
+
+    # Resolve mission
+    resolved_mission, env_cfg, _ = get_mission_name_and_config(ctx, mission, variants_arg=variant, cogs=cogs)
+    if steps is not None:
+        env_cfg.game.max_steps = steps
+
+    candidate_label = policy
+    pool_labels = pool
+    candidate_spec = get_policy_spec(ctx, policy)
+    try:
+        pool_specs = [parse_policy_spec(spec).to_policy_spec() for spec in pool]
+    except (ValueError, ModuleNotFoundError, httpx.HTTPError) as exc:
+        translated = _translate_error(exc)
+        console.print(f"[yellow]Error parsing pool policy: {translated}[/yellow]\n")
+        raise typer.Exit(1) from exc
+
+    pickup_module.pickup(
+        console,
+        candidate_spec,
+        pool_specs,
+        env_cfg=env_cfg,
+        mission_name=resolved_mission,
+        episodes=episodes,
+        seed=seed,
+        map_seed=map_seed,
+        action_timeout_ms=action_timeout_ms,
+        save_replay_dir=save_replay_dir,
+        candidate_label=candidate_label,
+        pool_labels=pool_labels,
+    )
+
+
+@app.command(
+    name="version",
+    help="Show version information for cogames and dependencies",
+    rich_help_panel="Info",
+)
 def version_cmd() -> None:
     def public_version(dist_name: str) -> str:
         return str(Version(importlib.metadata.version(dist_name)).public)
@@ -818,7 +1693,18 @@ def version_cmd() -> None:
     console.print(table)
 
 
-@app.command(name="policies", help="Show default policies and their shorthand names")
+@app.command(
+    name="policies",
+    help="Show available policy shorthand names",
+    rich_help_panel="Policies",
+    epilog="""[dim]Usage:[/dim]
+
+  Use these shorthand names with [cyan]--policy[/cyan] or [cyan]-p[/cyan]:
+
+  [cyan]cogames play -m arena -p class=random[/cyan]     Use random policy
+
+  [cyan]cogames play -m arena -p class=baseline[/cyan]   Use baseline policy""",
+)
 def policies_cmd() -> None:
     policy_registry = get_policy_registry()
     table = Table(show_header=False, box=None, show_lines=False, pad_edge=False)
@@ -832,26 +1718,48 @@ def policies_cmd() -> None:
     console.print(table)
 
 
-@app.command(name="login", help="Authenticate with CoGames server")
+@app.command(
+    name="login",
+    help="Authenticate with CoGames server",
+    rich_help_panel="Tournament",
+    epilog="""[dim]Examples:[/dim]
+
+[cyan]cogames login[/cyan]                       Authenticate with default server
+
+[cyan]cogames login --force[/cyan]               Re-authenticate even if already logged in""",
+    add_help_option=False,
+)
 def login_cmd(
     server: str = typer.Option(
         DEFAULT_COGAMES_SERVER,
-        "--server",
-        "-s",
-        help="CoGames server URL",
+        "--login-server",
+        metavar="URL",
+        help="Authentication server URL",
+        rich_help_panel="Server",
     ),
     force: bool = typer.Option(
         False,
         "--force",
         "-f",
-        help="Get a new token even if one already exists",
+        help="Re-authenticate even if already logged in",
+        rich_help_panel="Options",
     ),
     timeout: int = typer.Option(
         300,
         "--timeout",
         "-t",
+        metavar="SECS",
         help="Authentication timeout in seconds",
-        min=1,
+        rich_help_panel="Options",
+    ),
+    _help: bool = typer.Option(
+        False,
+        "--help",
+        "-h",
+        help="Show this message and exit",
+        is_eager=True,
+        callback=_help_callback,
+        rich_help_panel="Other",
     ),
 ) -> None:
     from urllib.parse import urlparse
@@ -877,29 +1785,211 @@ def login_cmd(
         raise typer.Exit(1)
 
 
-app.command(name="submissions", help="Show your uploaded policies and tournament submissions")(submissions_cmd)
+app.command(
+    name="submissions",
+    help="Show your uploads and tournament submissions",
+    rich_help_panel="Tournament",
+    epilog="""[dim]Examples:[/dim]
+
+[cyan]cogames submissions[/cyan]                         All your uploads
+
+[cyan]cogames submissions --season beta-cogsguard[/cyan]           Submissions in a season
 
-app.command(name="seasons", help="List available tournament seasons")(seasons_cmd)
+[cyan]cogames submissions -p my-policy[/cyan]            Info on a specific policy""",
+    add_help_option=False,
+)(submissions_cmd)
+
+app.command(
+    name="seasons",
+    help="List currently running tournament seasons",
+    rich_help_panel="Tournament",
+    add_help_option=False,
+)(seasons_cmd)
 
 app.command(
     name="leaderboard",
     help="Show tournament leaderboard for a season",
+    rich_help_panel="Tournament",
+    epilog="""[dim]Examples:[/dim]
+
+[cyan]cogames leaderboard --season beta-cogsguard[/cyan]           View rankings""",
+    add_help_option=False,
 )(leaderboard_cmd)
 
 
-@app.command(name="validate-policy", help="Validate the policy loads and runs a single step")
+@app.command(
+    name="diagnose",
+    help="Run diagnostic evals for a policy checkpoint",
+    rich_help_panel="Evaluate",
+    epilog="""[dim]Examples:[/dim]
+
+[cyan]cogames diagnose ./train_dir/my_run[/cyan]                         Default diagnostics
+
+[cyan]cogames diagnose lstm -S tournament[/cyan]                         Tournament suite
+
+[cyan]cogames diagnose lstm -c 4 -c 8 -e 5[/cyan]                        Custom cog counts""",
+    add_help_option=False,
+)
+def diagnose_cmd(
+    policy: str = typer.Argument(
+        ...,
+        metavar="POLICY",
+        help=f"Policy specification: {policy_arg_example}",
+    ),
+    # --- Evaluation ---
+    mission_set: Literal[
+        "diagnostic_evals",
+        "integrated_evals",
+        "spanning_evals",
+        "thinky_evals",
+        "tournament",
+        "all",
+    ] = typer.Option(
+        "diagnostic_evals",
+        "--mission-set",
+        "-S",
+        metavar="SET",
+        help="Eval suite to run",
+        rich_help_panel="Evaluation",
+    ),
+    experiments: Optional[list[str]] = typer.Option(  # noqa: B008
+        None,
+        "--experiments",
+        metavar="NAME",
+        help="Specific experiments (subset of mission set)",
+        rich_help_panel="Evaluation",
+    ),
+    cogs: Optional[list[int]] = typer.Option(  # noqa: B008
+        None,
+        "--cogs",
+        "-c",
+        metavar="N",
+        help="Agent counts to test (repeatable)",
+        rich_help_panel="Evaluation",
+    ),
+    # --- Simulation ---
+    steps: int = typer.Option(
+        1000,
+        "--steps",
+        "-s",
+        metavar="N",
+        help="Max steps per episode",
+        rich_help_panel="Simulation",
+    ),
+    episodes: int = typer.Option(
+        3,
+        "--episodes",
+        "-e",
+        metavar="N",
+        help="Episodes per case",
+        rich_help_panel="Simulation",
+    ),
+    # --- Help ---
+    _help: bool = typer.Option(
+        False,
+        "--help",
+        "-h",
+        help="Show this message and exit",
+        is_eager=True,
+        callback=_help_callback,
+        rich_help_panel="Other",
+    ),
+) -> None:
+    script_path = Path(__file__).resolve().parents[2] / "scripts" / "run_evaluation.py"
+
+    cmd = [sys.executable, str(script_path)]
+    cmd.extend(["--mission-set", mission_set])
+
+    if experiments:
+        cmd.append("--experiments")
+        cmd.extend(experiments)
+
+    if cogs:
+        cmd.append("--cogs")
+        cmd.extend(str(c) for c in cogs)
+
+    cmd.extend(["--steps", str(steps)])
+    cmd.extend(["--repeats", str(episodes)])
+    cmd.append("--no-plots")
+
+    cmd.extend(["--policy", policy])
+
+    console.print("[cyan]Running diagnostic evaluation...[/cyan]")
+    console.print(f"[dim]{' '.join(cmd)}[/dim]")
+    subprocess.run(cmd, check=True)
+
+
+def _resolve_season(server: str, season_name: str | None = None) -> SeasonInfo:
+    try:
+        if season_name is not None:
+            info = fetch_season_info(server, season_name)
+            console.print(f"[dim]Using season: {info.name}[/dim]")
+        else:
+            info = fetch_default_season(server)
+            console.print(f"[dim]Using default season: {info.name}[/dim]")
+        return info
+    except Exception as e:
+        console.print(f"[red]Could not fetch season from server:[/red] {e}")
+        console.print("Specify a season explicitly with [cyan]--season[/cyan]")
+        raise typer.Exit(1) from None
+
+
+@app.command(
+    name="validate-policy",
+    help="Validate the policy loads and runs for at least a single step",
+    rich_help_panel="Policies",
+    add_help_option=False,
+)
 def validate_policy_cmd(
     ctx: typer.Context,
-    policy: str = typer.Argument(
+    policy: str = typer.Option(
         ...,
+        "--policy",
+        "-p",
+        metavar="POLICY",
         help=f"Policy specification: {policy_arg_example}",
+        rich_help_panel="Policy",
     ),
     setup_script: Optional[str] = typer.Option(
         None,
         "--setup-script",
         help="Path to a Python setup script to run before loading the policy",
+        rich_help_panel="Policy",
+    ),
+    season: Optional[str] = typer.Option(
+        None,
+        "--season",
+        metavar="SEASON",
+        help="Tournament season (determines which game to validate against)",
+        rich_help_panel="Tournament",
+    ),
+    server: str = typer.Option(
+        DEFAULT_SUBMIT_SERVER,
+        "--server",
+        metavar="URL",
+        help="Tournament server URL (used to resolve default season)",
+        rich_help_panel="Server",
+    ),
+    _help: bool = typer.Option(
+        False,
+        "--help",
+        "-h",
+        help="Show this message and exit",
+        is_eager=True,
+        callback=_help_callback,
+        rich_help_panel="Other",
     ),
 ) -> None:
+    season_info = _resolve_season(server, season)
+    entry_pool_info = next((p for p in season_info.pools if p.name == season_info.entry_pool), None)
+    if not entry_pool_info or not entry_pool_info.config_id:
+        console.print("[red]No entry config found for season[/red]")
+        raise typer.Exit(1)
+
+    with TournamentServerClient(server_url=server) as client:
+        config_data = client.get_config(entry_pool_info.config_id)
+    env_cfg = MettaGridConfig.model_validate(config_data)
+
     if setup_script:
         import subprocess
         import sys
@@ -923,7 +2013,7 @@ def validate_policy_cmd(
         console.print("[green]Setup script completed[/green]")
 
     policy_spec = get_policy_spec(ctx, policy)
-    validate_policy_spec(policy_spec)
+    validate_policy_spec(policy_spec, env_cfg)
     console.print("[green]Policy validated successfully[/green]")
     raise typer.Exit(0)
 
@@ -936,66 +2026,125 @@ def _parse_init_kwarg(value: str) -> tuple[str, str]:
     return key.replace("-", "_"), val
 
 
-@app.command(name="upload", help="Upload a policy to CoGames")
+@app.command(
+    name="upload",
+    help="Upload a policy to CoGames",
+    rich_help_panel="Tournament",
+    epilog="""[dim]Examples:[/dim]
+
+[cyan]cogames upload -p ./train_dir/my_run -n my-policy[/cyan]       Upload and submit to default season
+
+[cyan]cogames upload -p ./run -n my-policy --season beta-cvc[/cyan]  Upload and submit to specific season
+
+[cyan]cogames upload -p ./run -n my-policy --no-submit[/cyan]        Upload without submitting
+
+[cyan]cogames upload -p lstm -n my-lstm --dry-run[/cyan]             Validate only""",
+    add_help_option=False,
+)
 def upload_cmd(
     ctx: typer.Context,
+    # --- Upload ---
+    name: str = typer.Option(
+        ...,
+        "--name",
+        "-n",
+        metavar="NAME",
+        help="Name for your uploaded policy",
+        rich_help_panel="Upload",
+    ),
+    # --- Policy ---
     policy: str = typer.Option(
         ...,
         "--policy",
         "-p",
+        metavar="POLICY",
         help=f"Policy specification: {policy_arg_example}",
-    ),
-    name: str = typer.Option(
-        ...,
-        "--name",
-        "-n",
-        help="Policy name for the upload",
+        rich_help_panel="Policy",
     ),
     init_kwarg: Optional[list[str]] = typer.Option(  # noqa: B008
         None,
         "--init-kwarg",
         "-k",
-        help="Policy init kwargs as key=value (can be repeated)",
+        metavar="KEY=VAL",
+        help="Policy init kwargs (can be repeated)",
+        rich_help_panel="Policy",
     ),
+    # --- Files ---
     include_files: Optional[list[str]] = typer.Option(  # noqa: B008
         None,
         "--include-files",
         "-f",
-        help="Files or directories to include (can be specified multiple times)",
+        metavar="PATH",
+        help="Files or directories to include (can be repeated)",
+        rich_help_panel="Files",
     ),
-    login_server: str = typer.Option(
-        DEFAULT_COGAMES_SERVER,
-        "--login-server",
-        help="Login/authentication server URL",
+    setup_script: Optional[str] = typer.Option(
+        None,
+        "--setup-script",
+        metavar="PATH",
+        help="Python setup script to run before loading the policy",
+        rich_help_panel="Files",
     ),
-    server: str = typer.Option(
-        DEFAULT_SUBMIT_SERVER,
-        "--server",
-        "-s",
-        help="Server URL",
+    # --- Tournament ---
+    season: Optional[str] = typer.Option(
+        None,
+        "--season",
+        metavar="SEASON",
+        help="Tournament season (default: server's default season)",
+        rich_help_panel="Tournament",
+    ),
+    no_submit: bool = typer.Option(
+        False,
+        "--no-submit",
+        help="Upload without submitting to a season",
+        rich_help_panel="Tournament",
     ),
+    # --- Validation ---
     dry_run: bool = typer.Option(
         False,
         "--dry-run",
         help="Run validation only without uploading",
+        rich_help_panel="Validation",
     ),
     skip_validation: bool = typer.Option(
         False,
         "--skip-validation",
         help="Skip policy validation in isolated environment",
+        rich_help_panel="Validation",
     ),
-    setup_script: Optional[str] = typer.Option(
-        None,
-        "--setup-script",
-        help="Path to a Python setup script to run before loading the policy",
+    # --- Server ---
+    login_server: str = typer.Option(
+        DEFAULT_COGAMES_SERVER,
+        "--login-server",
+        metavar="URL",
+        help="Authentication server URL",
+        rich_help_panel="Server",
+    ),
+    server: str = typer.Option(
+        DEFAULT_SUBMIT_SERVER,
+        "--server",
+        metavar="URL",
+        help="Tournament server URL",
+        rich_help_panel="Server",
+    ),
+    # --- Help ---
+    _help: bool = typer.Option(
+        False,
+        "--help",
+        "-h",
+        help="Show this message and exit",
+        is_eager=True,
+        callback=_help_callback,
+        rich_help_panel="Other",
     ),
 ) -> None:
-    """Upload a policy to CoGames.
+    season_info = _resolve_season(server, season)
+
+    has_entry_config = any(p.config_id for p in season_info.pools if p.name == season_info.entry_pool)
+    if not has_entry_config and not skip_validation:
+        console.print("[yellow]Warning: No entry config found for season. Skipping validation.[/yellow]")
+        skip_validation = True
 
-    This command validates your policy, creates an upload package,
-    and uploads it to the CoGames server. You can then submit it
-    to tournaments using 'cogames submit'.
-    """
     init_kwargs: dict[str, str] = {}
     if init_kwarg:
         for kv in init_kwarg:
@@ -1013,47 +2162,73 @@ def upload_cmd(
         skip_validation=skip_validation,
         init_kwargs=init_kwargs if init_kwargs else None,
         setup_script=setup_script,
+        validation_season=season_info.name,
+        season=season_info.name if not no_submit else None,
     )
 
     if result:
         console.print(f"[green]Upload complete: {result.name}:v{result.version}[/green]")
-        console.print(f"\nTo submit to a tournament: cogames submit {result.name}:v{result.version} --season <name>")
+        if result.pools:
+            console.print(f"[dim]Added to pools: {', '.join(result.pools)}[/dim]")
+            console.print(f"[dim]Results:[/dim] {results_url_for_season(server, season_info.name)}")
+        elif no_submit:
+            console.print(f"\nTo submit to a tournament: cogames submit {result.name}:v{result.version}")
 
 
-@app.command(name="submit", help="Submit an uploaded policy to a tournament season")
+@app.command(
+    name="submit",
+    help="Submit a policy to a tournament season",
+    rich_help_panel="Tournament",
+    epilog="""[dim]Examples:[/dim]
+
+[cyan]cogames submit my-policy[/cyan]                                   Submit to default season
+
+[cyan]cogames submit my-policy:v3 --season beta-cvc[/cyan]              Submit specific version to specific season""",
+    add_help_option=False,
+)
 def submit_cmd(
     policy_name: str = typer.Argument(
         ...,
+        metavar="POLICY",
         help="Policy name (e.g., 'my-policy' or 'my-policy:v3' for specific version)",
     ),
-    season: str = typer.Option(
-        ...,
+    season: Optional[str] = typer.Option(
+        None,
         "--season",
-        help="Tournament season name (required)",
+        metavar="SEASON",
+        help="Tournament season name",
+        rich_help_panel="Tournament",
     ),
     login_server: str = typer.Option(
         DEFAULT_COGAMES_SERVER,
         "--login-server",
-        help="Login/authentication server URL",
+        metavar="URL",
+        help="Authentication server URL",
+        rich_help_panel="Server",
     ),
     server: str = typer.Option(
         DEFAULT_SUBMIT_SERVER,
         "--server",
         "-s",
-        help="Server URL",
+        metavar="URL",
+        help="Tournament server URL",
+        rich_help_panel="Server",
+    ),
+    _help: bool = typer.Option(
+        False,
+        "--help",
+        "-h",
+        help="Show this message and exit",
+        is_eager=True,
+        callback=_help_callback,
+        rich_help_panel="Other",
     ),
 ) -> None:
-    """Submit an uploaded policy to a tournament season.
-
-    First upload your policy with 'cogames upload', then submit it to
-    a tournament season with this command.
-
-    Examples:
-      cogames submit my-policy --season beta
-      cogames submit my-policy:v3 --season beta
-    """
     import httpx
 
+    season_info = _resolve_season(server, season)
+    season_name = season_info.name
+
     client = TournamentServerClient.from_login(server_url=server, login_server=login_server)
     if not client:
         raise typer.Exit(1)
@@ -1065,7 +2240,7 @@ def submit_cmd(
         raise typer.Exit(1) from None
 
     version_str = f"[dim]:v{version}[/dim]" if version is not None else "[dim] (latest)[/dim]"
-    console.print(f"[bold]Submitting {name}[/bold]{version_str} to season '{season}'\n")
+    console.print(f"[bold]Submitting {name}[/bold]{version_str} to season '{season_name}'\n")
 
     with client:
         pv = client.lookup_policy_version(name=name, version=version)
@@ -1076,12 +2251,12 @@ def submit_cmd(
             raise typer.Exit(1)
 
         try:
-            result = client.submit_to_season(season, pv.id)
+            result = client.submit_to_season(season_name, pv.id)
         except httpx.HTTPStatusError as exc:
             if exc.response.status_code == 404:
-                console.print(f"[red]Season '{season}' not found[/red]")
+                console.print(f"[red]Season '{season_name}' not found[/red]")
             elif exc.response.status_code == 409:
-                console.print(f"[red]Policy already submitted to season '{season}'[/red]")
+                console.print(f"[red]Policy already submitted to season '{season_name}'[/red]")
             else:
                 console.print(f"[red]Submit failed with status {exc.response.status_code}[/red]")
                 console.print(f"[dim]{exc.response.text}[/dim]")
@@ -1090,33 +2265,49 @@ def submit_cmd(
             console.print(f"[red]Submit failed:[/red] {exc}")
             raise typer.Exit(1) from exc
 
-    console.print(f"\n[bold green]Submitted to season '{season}'[/bold green]")
+    console.print(f"\n[bold green]Submitted to season '{season_name}'[/bold green]")
     if result.pools:
-        console.print(f"[dim]Pools: {', '.join(result.pools)}[/dim]")
+        console.print(f"[dim]Added to pools: {', '.join(result.pools)}[/dim]")
+    console.print(f"[dim]Results:[/dim] {results_url_for_season(server, season_name)}")
+    console.print(f"[dim]CLI:[/dim] cogames leaderboard --season {season_name}")
+
 
+@app.command(
+    name="docs",
+    help="Print documentation (run without arguments to see available docs)",
+    rich_help_panel="Info",
+    epilog="""[dim]Examples:[/dim]
+
+  [cyan]cogames docs[/cyan]                             List available documents
 
-@app.command(name="docs", help="Print documentation")
+  [cyan]cogames docs readme[/cyan]                      Print README
+
+  [cyan]cogames docs mission[/cyan]                     Print mission briefing""",
+    add_help_option=False,
+)
 def docs_cmd(
-    doc_name: Optional[str] = typer.Argument(None, help="Document name to print"),
+    doc_name: Optional[str] = typer.Argument(
+        None,
+        metavar="DOC",
+        help="Document name (readme, mission, technical_manual, scripted_agent, evals, mapgen)",
+    ),
+    _help: bool = typer.Option(
+        False,
+        "--help",
+        "-h",
+        help="Show this message and exit",
+        is_eager=True,
+        callback=_help_callback,
+    ),
 ) -> None:
-    """Print a documentation file.
-
-    Available documents:
-      - readme: README.md - CoGames overview and documentation
-      - mission: MISSION.md - Mission briefing for Machina VII Deployment
-      - technical_manual: TECHNICAL_MANUAL.md - Technical manual for Cogames
-      - scripted_agent: Scripted agent policy documentation
-      - evals: Evaluation missions documentation
-      - mapgen: Cogs vs Clips map generation documentation
-    """
     # Hardcoded mapping of document names to file paths and descriptions
     package_root = Path(__file__).parent.parent.parent
     docs_map: dict[str, tuple[Path, str]] = {
         "readme": (package_root / "README.md", "CoGames overview and documentation"),
-        "mission": (package_root / "MISSION.md", "Mission briefing for Machina VII Deployment"),
+        "mission": (package_root / "MISSION.md", "Mission briefing for CogsGuard Deployment"),
         "technical_manual": (package_root / "TECHNICAL_MANUAL.md", "Technical manual for Cogames"),
         "scripted_agent": (
-            Path(__file__).parent / "policy" / "scripted_agent" / "README.md",
+            Path(__file__).parent / "docs" / "SCRIPTED_AGENT.md",
             "Scripted agent policy documentation",
         ),
         "evals": (