Challenge Authoring Quickstart

This template (netsim-template) ships with only one canonical example challenge: 01 — Ethernet Basics. After you fork this template downstream, follow the workflow below to add your own challenges.

Directory layout

docs/challenges/
├── index.md                    ← This file (challenge index)
├── 01-ethernet-basics/         ← Canonical example
│   ├── config.yaml             ← Challenge definition (topology, protocols, events, flag, win_condition)
│   └── index.md                ← Challenge story and hints
├── flags.secret.yaml.example   ← Flag secret template (copy to flags.secret.yaml and add it to .gitignore before committing)
└── <your-new-challenge>/       ← Add new challenges following the example structure

Steps to add a new challenge

1. Copy 01-ethernet-basics/ into a new directory (we suggest the NN-slug naming pattern, e.g. 02-arp-poisoning/).
2. Edit config.yaml: write the metadata, topology, protocols, events, and win_condition following the DSL v2 spec in docs/dev/extending.md.
3. Edit index.md: write your challenge story, objectives, and hints.
4. Add the new challenge's flag mapping to flags.secret.yaml.
5. Run pnpm validate:challenges to confirm the schema passes.
6. Add a link to the new challenge under sidebar['/challenges/'] in .vitepress/config.mts.
7. Run pnpm docs:dev to preview locally.

Further reading

• System architecture — SimNet's core engine and data flow
• Adding new challenges — Full DSL v2 reference and every available field