fix(onboarding): improve onboarding instructions

Author: dineshpinto

docs/hackathon/0-onboarding.mdx

@@ -16,35 +16,34 @@ import CreateKey from "/static/img/verifiable-ai-hackathon/create-key.png";
 
 # Onboarding
 
-Welcome to the **Verifiable AI Hackathon**!
-This guide will walk you through setting up your development environment, including Google Cloud infrastructure, API credentials, and gcloud CLI access.
+Welcome to the **Verifiable AI Hackathon**! 🎉
+
+This guide walks you through the **four-step setup** to ensure you have the necessary access and tools to start building.
 
 ## Before You Begin
 
-- **Time Estimate:** 15-20 minutes to complete the entire setup
-- **Support Channel:** [Telegram Support Group](https://t.me/+StI5VEIvtIg2ODlh)
+- **Estimated Time:** ~15-20 minutes
+- **Need Help?** Join our [Telegram Support Group](https://t.me/+StI5VEIvtIg2ODlh)
 
-## Step 1: Google Account Setup
+## Step 1: Set up your Google account
 
 ### Prerequisites
 
-- A Google account (existing or newly created)
-- This account will be your primary access point for all hackathon resources
+- A Google account (existing or newly created) - this will be your access point for all hackathon resources
 
-### Registration Process
+### Registration & access
 
 1. Submit your Google account email during hackathon registration (i.e. the Google Form you submitted)
-2. Access to the `verifiable-ai-hackathon` Google Cloud project will be granted on **March 6th** (one day before the hackathon)
-3. Verify your access by visiting the [Google Cloud Console](https://console.cloud.google.com/welcome?project=verifiable-ai-hackathon)
-4. When access is granted, you'll see this confirmation screen:
+2. Access to the `verifiable-ai-hackathon` Google Cloud project will be granted on **March 6th** (i.e. one day before the hackathon)
+3. Verify your access by visiting the [Google Cloud Console](https://console.cloud.google.com/welcome?project=verifiable-ai-hackathon), when access is granted you will see the following confirmation:
 
    <img src={AccessGranted} style={{ width: 600 }} />
 
-## Step 2: API Credential Setup
+## Step 2: Set up API credentials
 
 ### Gemini API Keys
 
-1. Log into your registered Google account after you receive the approval
+1. Log into your registered Google account after you receive access to the `verifiable-ai-hackathon` Google Cloud project
 2. Visit the [Get a Gemini API key](https://aistudio.google.com/app/apikey) page
 3. Click on **Create API key** and select `verifiable-ai-hackathon` from the dropdown
 
@@ -54,48 +53,61 @@ This guide will walk you through setting up your development environment, includ
 
    <img src={CreateKey} style={{ width: 600 }} />
 
-5. Store your API key securely
+5. **Store your API key securely**
 
-### OpenRouter API Keys (Consensus Learning Track Only)
+<details>
+<summary>OpenRouter API Keys (Consensus Learning Track Only)</summary>
 
 If you're participating in the Consensus Learning track:
 
 1. Visit [OpenRouter](https://openrouter.ai) and create a free account
-2. Navigate to the [Settings page](https://openrouter.ai/settings/keys) to generate your API keys
+2. Navigate to the [Settings page](https://openrouter.ai/settings/keys) to generate your free API keys
 3. **Need higher limits?** Contact the Flare team on [Telegram](https://t.me/+StI5VEIvtIg2ODlh) with your team and VM instance name
 
-## Step 3: Set up gcloud CLI
+</details>
+
+## Step 3: Install & configure gcloud CLI
 
-1. **Download & install the gcloud CLI**
+### Install gcloud CLI
 
-   - Follow the [gcloud CLI installation guide](https://cloud.google.com/sdk/docs/install) steps for your OS
-   - Installation packages available for Windows, macOS, and Linux
+1. Follow the [gcloud CLI installation guide](https://cloud.google.com/sdk/docs/install) for Windows, macOS, or Linux.
 
-2. **Verify installation:**
+2. **Check installation:**
 
    ```bash
    gcloud version
    ```
 
-3. **Authenticate your CLI**
+### Authenticate & verify access
 
-   Use the same account used for hackathon registration
+1. **Authenticate your CLI**
+
+   Authenticate using the same Google account used for hackathon registration:
 
    ```bash
    gcloud auth login
    ```
 
-4. **Verify project access:**
+2. **Verify project access:**
 
    ```bash
    gcloud projects list
    ```
 
    The output should include `verifiable-ai-hackathon`
 
-## Step 4: Track template selection
+## Step 4: Select your track template
+
+### Prerequisites
+
+Ensure you have the following tools installed:
 
-1. Jump-start your development with one of these pre-configured templates:
+- [git](https://git-scm.com/downloads)
+- [uv](https://docs.astral.sh/uv/getting-started/installation/) (Python dependency management)
+- [Docker](https://www.docker.com) (for containerization)
+- [npm](https://nodejs.org/en/download) (for Social AI Agents & AI x DeFi tracks only)
+
+### Choose your template
 
 | Track              | Template Repository                                                                         |
 | ------------------ | ------------------------------------------------------------------------------------------- |
@@ -104,20 +116,30 @@ If you're participating in the Consensus Learning track:
 | AI x DeFi (DeFAI)  | [`flare-foundation/flare-ai-defai`](https://github.com/flare-foundation/flare-ai-defai)     |
 | Consensus Learning | [`flare-research/flare-ai-consensus`](https://github.com/flare-research/flare-ai-consensus) |
 
-2. Navigate to the template, and click on **Use this template** and **Create a new repository**
+### Clone & start building
+
+1. Navigate to the template, and click on **Use this template** → **Create a new repository**
 
    <img src={ChooseTemplate} style={{ width: 300 }} />
 
-3. **Clone the repo:**
+2. **Clone the repo:**
 
    ```bash
    git clone https://github.com/YOUR_REPO
    cd YOUR_REPO
    ```
 
-4. Follow the **README** in your chosen template for track-specific setup instructions
+3. Follow the **README** in your chosen template for track-specific setup instructions
 
-Happy hacking!
+**Happy building!**
+
+:::danger[Using hackathon compute resources]
+
+VM instances in `verifiable-ai-hackathon` are continuously monitored.
+
+**Any attempt** to use compute resources for activities outside the hackathon will result in immediate instance termination and possible suspension or permanent ban of account access privileges.
+
+:::
 
 ## Troubleshooting
 
@@ -129,20 +151,18 @@ Happy hacking!
 
 - **gcloud CLI Authentication Problems:**
 
-  - Run gcloud auth login --no-launch-browser if the browser auth flow fails
+  - Run `gcloud auth login --no-launch-browser` if the browser auth flow fails
   - Check if you have multiple Google accounts in your browser and select the correct one
 
 - **Windows-specific gcloud issues**
   - On Windows, when installing the gcloud CLI, gcloud installs its own basic shell as well.
   - We recommend using [git BASH](https://gitforwindows.org) for access to a full set of linux commands.
 
-:::tip[Still not able to bugfix?]
+## Need Help?
 
-If you are unable to fix your issue, feel free to reach out to the Flare team on [Telegram](https://t.me/+StI5VEIvtIg2ODlh) for support. When reaching out, include:
+If you're stuck, reach out to the Flare team on [Telegram](https://t.me/+StI5VEIvtIg2ODlh). Include:
 
-- Your team name
-- VM instance name
-- Screenshots of any error messages
+- Your **team name**
+- Your **VM instance name**
+- Screenshots of errors
 - Steps you've already attempted
-
-:::