@EwoutH You have done some incredible work with Mesa, it is really great!

I had some minor comments. I am going to hit approve so I don't slow down the process. When we get to Mesa 4 we will probably need to look holistically at the tutorials, but for another day.

Thanks a lot for your extensive review! Will process your comments.

@quaquel could you also give this a look, from your professional background?

The new tutorials are not all shown in the docs because getting_started.md has not been updated.

I will do all the updating, renaming and referencing once after the rest is settled

I fixed all the numbers, links and references. They are now also rendered in Readthedocs:

1. Working with AgentSets
2. Agent Activation
3. Event Scheduling & Time

Updating/adding tutorials is quite cumbersome with the current numbering systems. Open to ideas on how to improve this.

For now, some pointers, if anyone needs to do this in the future:

1. Always use relative links with .ipynb extension

   ✅ [Tutorial Name](N_tutorial_name.ipynb)
   ❌ [Tutorial Name](https://mesa.readthedocs.io/.../N_tutorial_name.html)
   ❌ [Tutorial Name](N_tutorial_name.html)

2. When renumbering a tutorial, update:

   • Filename
   • All links pointing TO it from other tutorials
   • Colab/Binder badge URLs in its header
   • References in tutorial descriptions ("builds on [X]...")

3. Always update these files when adding/reordering:

   • docs/getting_started.md - tutorials list
   • docs/overview.md - navigation sidebar

4. Common patterns to search for:

   • "Next Steps" sections
   • "Tutorial Description" prerequisite references
   • "This is from the [X tutorial]..." in code explanations
   • Badge URLs: colab-badge and mybinder links

A couple of high-level remarks:

• Why separate AgentSet and agent activation? I would also expect agent activation to come before the other functionality of AgentSet
• I would consider leaving out the remark on before Mesa 3 and just talk about common activation patterns instead. Mesa 2 is ancient history by now.
• I would not discuss model.steps at all. I would like to delete that on Mesa 4 asap.
• On Schedule, I suggest reordering it: start, end, interval, count.

• Why separate AgentSet and agent activation? I would also expect agent activation to come before the other functionality of AgentSet

I first tried it in one but it got quite long. I choose for this order because then you first learn about selections and subsets of agents, and then on letting them do stuff.

On the other points, I agree, I will try to find some time. Otherwise it can be a follow-up PR.

Merging, I think this is a net improvement. Any follow-up PRs are welcome.