feat: add scaffolding script for new adventures

.devcontainer/devcontainer.json

@@ -0,0 +1,27 @@
+{
+  "name": "Open Ecosystem Challenges",
+  "image": "mcr.microsoft.com/devcontainers/base:bullseye",
+  "features": {
+    "ghcr.io/devcontainers/features/python:1": {
+      "version": "3.12"
+    }
+  },
+  "postCreateCommand": "bash .devcontainer/post-create.sh",
+  "forwardPorts": [8000],
+  "portsAttributes": {
+    "8000": {
+      "label": "MkDocs",
+      "onAutoForward": "openPreview"
+    }
+  },
+  "customizations": {
+    "vscode": {
+      "extensions": [
+        "ms-python.python",
+        "yzhang.markdown-all-in-one",
+        "davidanson.vscode-markdownlint"
+      ]
+    }
+  }
+}
+

.devcontainer/post-create.sh

@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+lib/shared/init.sh
+
+echo "→ Installing mkdocs-material..."
+pip install --quiet mkdocs-material mkdocs-monorepo-plugin
+
+echo "✓ Done! Run 'mkdocs serve' to start the docs server."
+

Makefile

@@ -0,0 +1,21 @@
+# ==============================================================================
+# Open Ecosystem Challenges
+# ==============================================================================
+
+.PHONY: help new-adventure docs
+
+# Default target - show help
+help:
+	@echo "Open Ecosystem Challenges - Available Commands:"
+	@echo ""
+	@echo "  make new-adventure   Scaffold a new adventure from an approved idea"
+	@echo "  make docs            Start the MkDocs documentation server"
+
+# ------------------------------------------------------------------------------
+
+new-adventure:
+	@scripts/new-adventure.sh
+
+docs:
+	@mkdocs serve
+

docs/contributing/adventure-ideas.md

@@ -59,7 +59,7 @@ Adventure 01 is a useful reference: Beginner introduces Argo CD ApplicationSets
 
 1. **Create a new file** in `ideas/` named `your-adventure-name.md`
 2. **Use the template** below to describe your idea
-3. **[Open a pull request](https://github.com/dynatrace-oss/open-ecosystem-challenges/compare)** with the title `Adventure Idea: Your Adventure Name`
+3. **[Open a pull request](https://github.com/dynatrace-oss/open-ecosystem-challenges/compare)** with the title `Adventure Idea: [emoji] Your Adventure Name`
 
 No issue required. Submit your idea directly as a PR.
 
@@ -68,7 +68,7 @@ No issue required. Submit your idea directly as a PR.
 Use this structure for your proposal. The three-level format is recommended but not required. Adjust based on your idea.
 
 ```markdown
-# Adventure Idea: [Your Adventure Name]
+# Adventure Idea: [emoji] [Your Adventure Name]
 
 ## Overview
 

docs/contributing/adventures.md

@@ -22,8 +22,6 @@ An adventure consists of:
 
 Use `00` as the adventure number during development. When your adventure is scheduled for release, maintainers will assign the final number and move it out of `planned/`.
 
-If `adventures/planned/` doesn't exist yet, create it.
-
 ```
 adventures/planned/00-adventure-name/
 ├── README.md                    # Brief intro + link to docs
@@ -53,43 +51,45 @@ adventures/planned/00-adventure-name/
 
 ## Step-by-Step
 
-### 1. Configure the Devcontainer
-
-Start by setting up the environment. Check an existing adventure with a similar setup as a blueprint for what you need. For Kubernetes-based adventures, [Adventure 01](../../adventures/01-echoes-lost-in-orbit/) is a good reference.
+### 1. Scaffold the Files
 
-Create a devcontainer for each level in `.devcontainer/00-adventure-name_NN-level/` (e.g., `01-beginner`, `02-intermediate`, `03-expert`). The number prefix on levels ensures proper sorting in the GitHub UI.
+Run the scaffolding script to generate the skeleton for your adventure level:
 
-**devcontainer.json:**
-```json
-{
-  "name": "Adventure 00 | 🟢 Beginner",
-  "image": "mcr.microsoft.com/devcontainers/base:bullseye",
-  "features": {
-    // Add required features (docker, kubectl, etc.)
-  },
-  "postCreateCommand": "bash .devcontainer/00-adventure-name_01-beginner/post-create.sh",
-  "postStartCommand": "bash .devcontainer/00-adventure-name_01-beginner/post-start.sh",
-  "forwardPorts": []
-}
+```bash
+make new-adventure
 ```
 
+This will prompt you to select an adventure and level, then generate:
+
+- `adventures/planned/00-adventure-name/` — adventure base with `README.md`, `mkdocs.yaml`, and `docs/index.md`
+- `adventures/planned/00-adventure-name/docs/<level>.md` — level guide
+- `adventures/planned/00-adventure-name/<level>/verify.sh` — verification script skeleton
+- `.devcontainer/00-adventure-name_NN-level/` — `devcontainer.json`, `post-create.sh`, `post-start.sh`
+
+Search for `TODO` in the generated files to find everything that needs filling in.
+
+### 2. Configure the Devcontainer
+
+Open the generated `.devcontainer/00-adventure-name_NN-level/` files and fill in the TODOs.
+
+For Kubernetes-based adventures, [Adventure 01](../../adventures/01-echoes-lost-in-orbit/) is a good reference for what features and setup scripts to use.
+
 **post-create.sh** runs once when the container is created:
-- Install CLI tools
+- Install CLI tools using setup scripts from `lib/`
 - Pull container images
 - Set up one-time configurations
 
 **post-start.sh** runs every time the container starts:
 - Start services (databases, clusters, etc.)
 - Apply initial state
-- Set up port forwarding
 
 **Infrastructure constraints:**
 
 Codespaces run on 2 cores and 8 GB RAM by default. Design your adventure within these limits — avoid memory-hungry workloads running in parallel and prefer lightweight images where possible.
 
 Post-create should finish in under 15 minutes, but aim for well under that.
 
-### 2. Build the Working Solution
+### 3. Build the Working Solution
 
 Implement the fully working version first. This is what the solved challenge looks like where everything works correctly.
 
@@ -98,7 +98,7 @@ This approach helps you:
 - Ensure the challenge is actually solvable
 - Have a reference implementation for the solution walkthrough
 
-### 3. Introduce the Challenges
+### 4. Introduce the Challenges
 
 Work backwards from your working solution to create the "broken" state participants will fix.
 
@@ -110,48 +110,21 @@ Good challenges are:
 
 Not sure if a challenge belongs at Beginner, Intermediate, or Expert? See [Calibrating Difficulty](adventure-ideas.md#calibrating-difficulty) for concrete signals and time expectations.
 
-### 4. Write the Documentation
+### 5. Write the Documentation
 
-**Level guide (e.g., `docs/beginner.md`):**
-- Story context
-- Objectives (what success looks like)
+Fill in the generated `docs/<level>.md` — it already contains the story, objectives, and learning outcomes from the idea file. Add:
+- Architecture overview (how the level is set up)
+- UI access instructions with port numbers
+- Where to start investigating
 - Helpful links to external docs
-- No spoilers
 
-See [Adventure 01's beginner level](../../adventures/01-echoes-lost-in-orbit/docs/beginner.md) for a good example.
+No spoilers — save those for a `solutions/<level>.md` file.
 
-**MkDocs configuration (`mkdocs.yaml`):**
-```yaml
-site_name: '00: Adventure Name'
-
-nav:
-  - Introduction: index.md
-  - 'Beginner': beginner.md
-  - 'Intermediate': intermediate.md
-  - 'Expert': expert.md
-  - 'Solutions':
-      - 'Beginner': solutions/beginner.md
-      - 'Intermediate': solutions/intermediate.md
-      - 'Expert': solutions/expert.md
-```
-
-### 5. Create the Verification Script
-
-Each level needs a `verify.sh` that validates the solution and generates a completion certificate.
-
-```bash
-#!/usr/bin/env bash
-set -euo pipefail
-
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-source "$SCRIPT_DIR/../../../lib/scripts/loader.sh"
+See [Adventure 01's beginner level](../../adventures/01-echoes-lost-in-orbit/docs/beginner.md) for a good example.
 
-# Your validation logic here using shared helpers
-# Browse lib/scripts/ to see what's available
+### 6. Create the Verification Script
 
-# On success, generate certificate
-check_submission_readiness "adventure-name" "level"
-```
+Fill in the generated `<level>/verify.sh`. It already has the boilerplate wired up — add your checks between the `print_sub_header` and the summary block.
 
 A good verification script:
 - Passes when the challenge is solved correctly
@@ -160,7 +133,9 @@ A good verification script:
 
 **Check outcomes, not implementation.** Verify the state the participant should have reached — a service is healthy, traces are present in Jaeger, a metric is being collected — not how they got there. File content checks (`check_file_contains`) are a last resort: they break for valid alternative solutions and reward copy-pasting over understanding. If your objective says "see traces in Jaeger", your verification should check that traces exist, not that a specific import was added.
 
-### 6. Final Test Run
+Browse `lib/scripts/` to see the available helper functions.
+
+### 7. Final Test Run
 
 Before submitting:
 
@@ -174,4 +149,4 @@ Before submitting:
 - **[Open a draft PR early.](https://github.com/dynatrace-oss/open-ecosystem-challenges/compare)** Get feedback on structure before completing everything.
 - **Ship one level at a time.** Each level gets its own PR — start with one, get it working, then build the next. Use `Part of #<tracking-issue>` on all but the last PR, and `Closes #<tracking-issue>` on the final one so the tracking issue closes automatically.
 - **Test on slow connections.** Codespace startup time matters.
-- **Write clear error messages.** Help participants understand what went wrong without giving away the solution.
+- **Write clear error messages.** Help participants understand what went wrong without giving away the solution.

ideas/.implemented/echoes-lost-in-orbit.md

@@ -1,17 +1,19 @@
-# Adventure Idea: Echoes Lost in Orbit
+# Adventure Idea: 🛰️ Echoes Lost in Orbit
 
 ## Overview
 
 **Theme:** The Intergalactic Union's communication network is in disarray. The Echo Server has gone silent, a language pack rollout for a new species is failing, and the hyperspace transport system needs robust observability. As an SRE, you'll restore order by fixing GitOps configurations, stabilizing progressive delivery, and building an observability pipeline.
 
 **Skills:**
+
 - Deploy reliably across multiple environments
 - Release safely using progressive delivery
 - Observe distributed systems with tracing and metrics
 
 **Technologies:** Argo CD, Argo Rollouts, OpenTelemetry, Prometheus, Jaeger, Kubernetes
 
 **Levels:**
+
 - 🟢 Beginner: Fix a broken multi-environment GitOps setup
 - 🟡 Intermediate: Stabilize a failing canary rollout with metrics-based analysis
 - 🔴 Expert: Build an observability pipeline to validate traffic before promoting releases