# Task: Generate CoGames Simulation Guide

You are updating the CoGames simulation guide. Read the current state of the codebase and produce an accurate guide for researchers and developers who want to understand how the CoGames simulation works under the hood — what agents see, what they can do, and how the game mechanics fit together.

## Rules

- Only write to `packages/mettagrid/nim/mettascope/tutorials/docs/simulation_guide.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 accurate and well-structured
- Be concise. Use short sentences, tables, and bullet points over prose. One sentence per concept — no filler, no fluff.
- The code calls them "agents" but we call them "cogs." Use "cog" (or "cogs") throughout the guide, not "agent."
- Use "junction" not "network node" when referring to capturable map points.
- Scoring: the goal is to hold junctions as much as possible over time (cumulative reward), not just max count at any instant.
- Define "use" and "bumping" before referencing them in mechanics sections.
- Death does not remove a cog from the game. It loses its gear and hearts but persists, and can return to its hub to get a new rig and restart.
- In the Missions section, list which variants the default game (machina_1) is composed of.
- 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 the simulation:

- `packages/cogames/` — docs, game definitions, missions, roles, variants, terrain generation
- `packages/mettagrid/python/src/mettagrid/config/` — action space and observation space specs

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 CoGames** — overview of the framework and Cogs vs Clips specifically
2. **Game Objective and Scoring** — what agents are trying to do, how rewards work
3. **Roles and Abilities** — each role, its stats, what it's good at
4. **Resources and Economy** — resource types, extraction, crafting, the cooperation loop
5. **Territory and Area-of-Effect** — how territory works, healing, damage
6. **Observations** — what agents see (token format, grid window, global tokens)
7. **Actions** — what agents can do (movement, noop, vibes, etc.)
8. **Variants** — describe the variant system and each major variant category as its own paragraph. Variants are composable modifiers that missions mix-and-match. Cover at least: clips behavior (adaptive, greedy, angry, none), roles (aligner, miner, scout, scrambler), resources and economy (elements, energy, solar, cargo, extractors, hearts), territory (heal team, damage strangers, buildings), terrain biomes (desert, forest, city, caves, distant resources), gear stations, vibes, days/night cycle, multi-team support. For each variant describe what it does in concrete game terms.
9. **Missions** — describe the mission system (Game → Mission → Variant composition). Cover machina_1 (aka cogsguard), four_score, and tutorial missions. For each mission note which variants it pulls in and what kind of gameplay it produces.
10. **Map Generation** — how maps are procedurally generated, biomes, buildings
11. **Running a Game** — how to launch a game, key commands
