Add Seqera Platform Automation side quest

.devcontainer/codespaces-dev/devcontainer.json

@@ -47,7 +47,8 @@
         "vscode": {
             "extensions": [
                 "nf-core.nf-core-extensionpack",
-                "ms-vscode.live-server"
+                "ms-vscode.live-server",
+                "hashicorp.terraform"
             ],
             // Use Python from conda
             "settings": {

.devcontainer/devcontainer.json

@@ -27,7 +27,8 @@
         "vscode": {
             "extensions": [
                 "nf-core.nf-core-extensionpack",
-                "ms-vscode.live-server"
+                "ms-vscode.live-server",
+                "hashicorp.terraform"
             ],
             // Use Python from conda
             "settings": {

.devcontainer/install-platform-tools.sh

@@ -0,0 +1,99 @@
+#!/usr/bin/env bash
+
+# Install the tooling used by the platform_automation side quest:
+#   - terraform : provision compute environments and pipelines declaratively
+#   - tw        : the Seqera Platform CLI (tower-cli)
+#   - seqerakit : YAML-driven wrapper around tw for declarative Platform setup
+#   - az        : the Azure CLI, used by Terraform's azurerm provider (az login)
+#
+# These run at container startup (via setup.sh -> onCreateCommand) rather than
+# as devcontainer features. The production image (ghcr.io/nextflow-io/training)
+# is only rebuilt on pushes to master, so feature additions don't reach an
+# already-published image. Installing here makes the tools available in every
+# container immediately.
+#
+# Idempotent (skips tools that are already present) and architecture-aware
+# (amd64 + arm64) so re-runs and both CPU families are safe.
+set -euo pipefail
+
+TERRAFORM_VERSION="1.9.8"
+TW_VERSION="0.32.0"
+
+ARCH="$(uname -m)"
+
+# Make sure the download/extract tools the installs below rely on exist.
+ensure_pkg() {
+    local cmd="$1" pkg="$2"
+    if ! command -v "${cmd}" >/dev/null 2>&1; then
+        echo "Installing ${pkg}..."
+        apt-get update -qq && apt-get install -y -qq "${pkg}" >/dev/null
+    fi
+}
+
+ensure_pkg curl curl
+ensure_pkg unzip unzip
+
+# --- Terraform -------------------------------------------------------------
+if command -v terraform >/dev/null 2>&1; then
+    echo "terraform already installed: $(terraform version | head -n1)"
+else
+    case "${ARCH}" in
+        x86_64 | amd64) tf_arch="amd64" ;;
+        aarch64 | arm64) tf_arch="arm64" ;;
+        *) echo "Unsupported architecture for terraform: ${ARCH}" >&2; exit 1 ;;
+    esac
+    echo "Installing Terraform ${TERRAFORM_VERSION} (${tf_arch})..."
+    tmp="$(mktemp -d)"
+    curl -fSL "https://releases.hashicorp.com/terraform/${TERRAFORM_VERSION}/terraform_${TERRAFORM_VERSION}_linux_${tf_arch}.zip" -o "${tmp}/terraform.zip"
+    unzip -q "${tmp}/terraform.zip" -d "${tmp}"
+    install -m 0755 "${tmp}/terraform" /usr/local/bin/terraform
+    rm -rf "${tmp}"
+fi
+
+# --- Seqera CLI (tw) -------------------------------------------------------
+# tower-cli only publishes a native Linux binary for x86_64; on arm64 install
+# the architecture-independent JAR (Java is provided by the java feature).
+if command -v tw >/dev/null 2>&1; then
+    echo "tw already installed: $(tw --version 2>/dev/null | head -n1)"
+else
+    base="https://github.com/seqeralabs/tower-cli/releases/download/v${TW_VERSION}"
+    case "${ARCH}" in
+        x86_64 | amd64)
+            echo "Installing Seqera CLI (tw) ${TW_VERSION} native binary for x86_64..."
+            curl -fSL "${base}/tw-linux-x86_64" -o /usr/local/bin/tw
+            chmod +x /usr/local/bin/tw
+            ;;
+        aarch64 | arm64)
+            echo "Installing Seqera CLI (tw) ${TW_VERSION} JAR for arm64..."
+            mkdir -p /usr/local/lib/tw
+            curl -fSL "${base}/tw-jar.jar" -o /usr/local/lib/tw/tw.jar
+            cat > /usr/local/bin/tw <<'EOF'
+#!/usr/bin/env bash
+exec java -jar /usr/local/lib/tw/tw.jar "$@"
+EOF
+            chmod +x /usr/local/bin/tw
+            ;;
+        *) echo "Unsupported architecture for tw: ${ARCH}" >&2; exit 1 ;;
+    esac
+fi
+
+# --- seqerakit -------------------------------------------------------------
+# Pure-Python (arch-independent) wrapper that drives tw from YAML. Installed
+# with the conda pip (python.defaultInterpreterPath = /opt/conda/bin/python),
+# so no PEP 668 override is needed. Depends on tw being on PATH (installed above).
+if command -v seqerakit >/dev/null 2>&1; then
+    echo "seqerakit already installed: $(seqerakit --version 2>/dev/null | head -n1)"
+else
+    echo "Installing seqerakit..."
+    pip install --quiet seqerakit
+fi
+
+# --- Azure CLI (az) --------------------------------------------------------
+# Microsoft's deb installer sets up the apt repo and pulls the right package
+# for the host architecture (amd64 + arm64 are both published).
+if command -v az >/dev/null 2>&1; then
+    echo "az already installed: $(az version --output tsv --query '"azure-cli"' 2>/dev/null | head -n1)"
+else
+    echo "Installing Azure CLI (az)..."
+    curl -sL https://aka.ms/InstallAzureCLIDeb | bash
+fi

.devcontainer/local-dev/devcontainer.json

@@ -49,7 +49,8 @@
         "vscode": {
             "extensions": [
                 "nf-core.nf-core-extensionpack",
-                "ms-vscode.live-server"
+                "ms-vscode.live-server",
+                "hashicorp.terraform"
             ],
             // Use Python from conda
             "settings": {

.devcontainer/local-features/uv-tools/install.sh

@@ -5,3 +5,5 @@
 uv tool install pre-commit
 uv tool install nf-core==3.5.2
 uv tool install "mkdocs-quiz>=1.5.2"
+# seqerakit: used by the platform_automation side quest
+uv tool install "seqerakit==0.5.7"

.devcontainer/setup.sh

@@ -30,4 +30,7 @@ cd /workspaces/training
 rm -rf /tmp/nf-test ~/.m2/repository
 echo "nf-test updated with v2 parser support"
 
+# Install the platform_automation side quest tools (terraform, tw, az)
+bash "$(dirname "$0")/install-platform-tools.sh"
+
 cat /usr/local/etc/vscode-dev-containers/first-run-notice.txt

.editorconfig

@@ -11,6 +11,10 @@ indent_style = space
 [*.{md,yml,yaml,html,css,scss,js}]
 indent_size = 2
 
+# Terraform's canonical `terraform fmt` style uses 2-space indentation
+[*.{tf,tfvars}]
+indent_size = 2
+
 # ignore python and markdown
 [*.{py,md}]
 indent_style = unset

.gitignore

@@ -27,3 +27,17 @@ _scripts/.venv/
 
 # Tutorial working directories (created by learners during exercises)
 hello-nf-core/core-hello/
+
+# Terraform (platform_automation side quest)
+**/.terraform/*
+.terraform.lock.hcl
+*.tfstate
+*.tfstate.*
+*.tfvars
+!*.tfvars.example
+crash.log
+crash.*.log
+
+# Agent/tooling local state
+.omc/
+**/.claude/.local/

docs/en/docs/side_quests/co_scientist/01_meet_coscientist.md

@@ -0,0 +1,109 @@
+# Meet CoScientist
+
+Working on the Seqera Platform means moving between the Launchpad, compute environments, datasets, and runs.
+CoScientist can drive all of that from a conversation, once it is connected to your workspace.
+In this lesson you open the chat, connect it to your training workspace, and have it inspect and register real Platform assets, so the rest of the course has a working agent to build on.
+
+---
+
+## 1. Open the chat and connect to your workspace.
+
+Navigate to [https://ai.seqera.io/chat](https://ai.seqera.io/chat) and sign in with your Seqera credentials.
+
+![The CoScientist chat after signing in](img/chat-landing.png)
+
+Use the **Workspace** selector in the top navigation to choose the provided training workspace.
+
+## 2. Confirm the connection and survey the workspace.
+
+!!! tip "Writing good prompts"
+
+    Be specific and state the action or output you want.
+    [Working with the agent](02_working_with_the_agent.md) covers prompting for intent in depth.
+
+Send one prompt to confirm CoScientist can see your workspace and to get a snapshot of what is already in it:
+
+```text
+Which Seqera workspace am I connected to? List the compute environments, the pipelines on the Launchpad, and the datasets you can see.
+```
+
+??? example "What CoScientist typically does"
+
+    It names the connected workspace and lists the compute environment(s), Launchpad pipelines, and datasets it can see.
+    The exact wording and the number of items will differ depending on the workspace state.
+
+The same access also covers reference genomes and data links.
+
+!!! note "Checkpoint"
+
+    CoScientist correctly names the **training workspace** and lists at least one compute environment, along with any pipelines and datasets (or reports that none exist yet).
+    If it cannot name the workspace, the connection is not set up; revisit step 1.
+
+## 3. Ask CoScientist what it can do.
+
+Get a baseline picture of the agent's capabilities in this workspace:
+
+```text
+What can you help me with in this workspace? What can you see and what actions can you take?
+```
+
+??? example "What CoScientist typically does"
+
+    It describes that it can help develop pipelines, launch and monitor runs, browse data, and act on GitHub.
+    The exact wording will differ from run to run.
+
+## 4. Add rnaseq-nf to the Launchpad.
+
+Ask CoScientist to register a pipeline on your behalf:
+
+```text
+Add the pipeline https://github.com/nextflow-io/rnaseq-nf to the Launchpad in this workspace, using the available compute environment and a tag to identify it as created by me.
+```
+
+CoScientist will confirm the action or ask which compute environment to use if more than one is available.
+
+!!! note "Checkpoint"
+
+    In the Seqera Platform web app, open **Launchpad**: an entry for `rnaseq-nf` is now present.
+
+![rnaseq-nf on the Launchpad](img/launchpad-rnaseq-nf.png)
+
+## 5. Understand what rnaseq-nf does.
+
+`rnaseq-nf` is a small RNA-seq quantification pipeline, a good size to develop and test against.
+It builds a Salmon index from a transcriptome (`INDEX`), runs quality control on the reads (`FASTQC`), quantifies transcript expression with Salmon (`QUANT`), and aggregates the results into a single report (`MULTIQC`).
+It ships a small chicken (`ggal`) test dataset, so a full run finishes in minutes.
+
+```mermaid
+graph LR
+    T[Transcriptome] --> INDEX[INDEX<br/>salmon index]
+    R[Reads] --> FASTQC[FASTQC<br/>quality control]
+    R --> QUANT[QUANT<br/>salmon quant]
+    INDEX --> QUANT
+    FASTQC --> MULTIQC[MULTIQC<br/>report]
+    QUANT --> MULTIQC
+    MULTIQC --> OUT[multiqc_report.html]
+```
+
+## 6. Inspect the compute environment.
+
+Ask CoScientist to read the configuration for the compute environment attached to the pipeline:
+
+```text
+Show me the details of the compute environment this pipeline will run on.
+```
+
+CoScientist reads the compute-environment configuration and returns the key fields.
+
+!!! note "Checkpoint"
+
+    CoScientist reports the compute environment name and platform (for example AWS Batch) matching the training compute environment.
+
+### Takeaway
+
+You connected CoScientist to your training workspace, had a first conversation, and used it to register and inspect a pipeline.
+It acts on real Platform assets on your behalf, with your own permissions.
+
+### What's next?
+
+In the next lesson, [learn how to work effectively with the agent](02_working_with_the_agent.md) before you start changing code.

docs/en/docs/side_quests/co_scientist/02_working_with_the_agent.md

@@ -0,0 +1,103 @@
+# Working with the agent
+
+CoScientist takes real actions on your workspace, so how you prompt and check it matters.
+In this lesson you launch a run that fails on a simple mistake, then drive the agent to fix it from the user side, without editing any pipeline code.
+Along the way you practise the habits that keep you in control: prompt for intent, verify what the agent did, and redirect it when it goes wrong.
+
+---
+
+## 1. Launch a run that will fail.
+
+`rnaseq-nf` ships its own test transcriptome and uses it by default.
+To create a failure to work with, launch the pipeline but override that default with a path that does not exist:
+
+```text
+Launch my rnaseq-nf on the Launchpad, but set the transcriptome parameter to /tmp/missing.fa so we have a failed run to work with.
+```
+
+The run fails almost immediately at the indexing step, because the file you pointed it at is not there.
+
+!!! note "Checkpoint"
+
+    A run for rnaseq-nf appears in the Runs list and fails quickly with a file-not-found error.
+
+## 2. Open the failed run from the Platform.
+
+CoScientist works in both directions.
+You launched this run from the chat; you can also reach the agent from a run in the Platform.
+Open the **Runs** list, select the failed run, and choose **Explain with AI**.
+This starts a CoScientist conversation loaded with that run's context, so you do not have to describe the failure yourself.
+
+![The Explain with AI button on a failed run](img/explain-with-ai.png)
+
+!!! note "Checkpoint"
+
+    Selecting **Explain with AI** opens a CoScientist conversation about the failed run.
+
+## 3. Prompt for intent.
+
+Ask the agent to work the problem, giving it the symptom and a clear goal rather than a vague instruction.
+
+=== "Better"
+
+    ```text
+    This rnaseq-nf run failed. Read the run log, tell me the cause, and propose how to fix the launch settings before changing anything.
+    ```
+
+=== "Vague"
+
+    ```text
+    Fix the pipeline.
+    ```
+
+The better prompt points the agent at the run log, asks it to explain before acting, and limits it to the launch settings.
+The vague one invites it to guess, and the guess is often wrong.
+
+??? example "What CoScientist typically does"
+
+    It reads the run log, reports that the transcriptome file could not be found, and proposes correcting the parameter to the default path.
+    The exact wording will differ from run to run.
+
+## 4. Verify what the agent says.
+
+Do not take the agent's diagnosis, or its "Done", at face value.
+Check its explanation against the actual run error, and confirm the cause is the parameter you set, not a problem in the pipeline.
+
+!!! warning
+
+    Treat the agent's "Done" as a claim to check, not a fact.
+    The Checkpoints in this side quest exist for this reason: each one is a real Platform state you confirm yourself, whatever the agent says it did.
+
+!!! note "Checkpoint"
+
+    From the run's own error, you have confirmed the failure is the missing transcriptome file you set at launch.
+
+## 5. Redirect the agent when it goes too far.
+
+The fix here is a launch parameter, not a code change.
+The default transcriptome ships with the pipeline, so fixing the run means dropping your override, not finding new data.
+If the agent offers to edit the pipeline, steer it back to the smallest fix:
+
+```text
+Don't change the pipeline code. Just remove the transcriptome override so the pipeline uses its default, and relaunch.
+```
+
+!!! note "Checkpoint"
+
+    The agent corrects only the launch parameter and leaves the pipeline code untouched.
+
+## 6. Re-launch and confirm the fix.
+
+With the parameter corrected, the run gets past the step that failed.
+
+!!! note "Checkpoint"
+
+    The new run launches and proceeds past the indexing step instead of failing immediately.
+
+### Takeaway
+
+You fixed a failed run entirely from the user side, without touching pipeline code, by prompting for intent, verifying the agent's diagnosis against the real error, and redirecting it to the smallest fix.
+
+### What's next?
+
+In the next lesson, [start developing with CoScientist](03_develop_with_coscientist.md), where you change the pipeline itself.