# Task: Generate Playing CoGames Tutorial

You are updating the mettascope player tutorial. Read the current state of the codebase and produce an accurate, beginner-friendly guide for someone who just opened mettascope and wants to understand what they're looking at and how to interact with it.

## Rules

- Only write to `packages/mettagrid/nim/mettascope/tutorials/docs/playing_cogames.md`
- If the output file already exists, read it first and update only the sections that are out of date based on current code. If it does not exist, create it from scratch.
- Do not edit any source code
- Do not invent mechanics you cannot find in the source code
- Keep it beginner-friendly but accurate
- Be concise. Use short sentences, tables, and bullet points over prose. One sentence per concept — no filler, no fluff. The view is top-down (like Factorio), not isometric.
- The code calls them "agents" but we call them "cogs." Use "cog" (or "cogs") throughout the tutorial, not "agent."
- Use "junction" not "network node" when referring to capturable map points.
- Unlocking camera focus can be done by pressing F again, clicking the tack icon, or dragging the map.
- Start the file with: `<!-- Auto-generated by claude-code. Edit the prompt, not this file. -->`

## Source directories to explore

Read through these directories to understand the current state of mettascope and cogames:

- `packages/mettagrid/nim/mettascope/src/mettascope/` — look for keybindings, mouse interactions, UI panels, rendering, playback controls, and any player-facing features
- `packages/cogames/` — read top-level docs and explore game definitions enough to explain what the player is watching

Use your judgement on which files matter. The game changes frequently so don't assume anything — read the code.

## Sections to produce

1. **What is Mettascope** — brief intro, what you're looking at when you open it
2. **Getting Started** — how to launch. Show these exact commands:
   - Web demo: `https://metta-ai.github.io/metta/mettascope/mettascope.html`
   - Play mode: `uv run cogames play --mission machina_1 --cogs 4`
   - Play mode with AI policy: `uv run cogames play -m machina_1 -p class=nlanky`
   - Replay mode: `uv run cogames replay ./path/to/replay.json.z`
   Then cover basic navigation (pan, zoom)
3. **Controls Reference** — keybindings table and mouse interactions, derived from source code
4. **Understanding the Game** — start by explaining what a Cog is (a team unit that can be either AI-controlled or player-controlled in play mode) and what Clips are (the automated adversary). Then cover junctions, territory, scoring. Explain that roles (miner, aligner, scrambler, scout) are optional gear-based specializations — agents start as generic cogs and can equip a role at a gear station. Not all missions use roles. Link to simulation guide for depth.
5. **UI Panels** — what each panel shows and when it's useful
6. **Tips** — practical advice for getting the most out of mettascope
