Run the Cloud course in an instance per participant

The Cloud course no longer starts from a team card. Each participant gets an
instance in the hackathon organization and a service account from the
organizers, creates a Kafka cluster, an agent workspace and a SQL workspace in
it, and fills in .env with snctl lookups in Lab 0.

- Lab 0 reads each address with snctl, creates the login topic and loads it.
  The seeders accept the cloud stack and name the course in their hints.
- Lab 2 selects from the source named after the topic, security.login_events,
  and offers psql through the SQL workspace gateway.
- Lab 4 says the SQL workspace needs read-write MCP access, and its deny
  example matches what the scripts print.
- Troubleshooting covers the snctl context, the SQL tools failing with
  connection_unavailable, read-only MCP access, and a slow approval.
- The doctor and the setup hints point at the instance, not a team card.
- What was run: Labs 1, 3 and 4 with every check on all three paths against a
  test instance on StreamNative Cloud.

Author: sijie

.env.cloud.example

@@ -1,29 +1,35 @@
-# The Cloud course: copy this file to .env (in the repo root) and paste the
-# values from your team card. .env is git-ignored: never commit it.
+# The Cloud course: copy this file to .env (in the repo root) and fill it in
+# from your instance on StreamNative Cloud. .env is git-ignored: never commit it.
 #
 #   cp .env.cloud.example .env
 #
+# labs/cloud/00-set-up.md, step 2, has the snctl command for each address.
 # (The Local course writes its own .env: see labs/local/00-set-up.md.)
 
-# ---------------------------------------------------------------- team card --
+# -------------------------------------------------- from the organizers --
 
-# Service-account API key (API Key v2) for the hosted Agent Engine API,
-# Kafka and Schema Registry. OAuth MCP servers use a separate browser login.
+# Your service account's API key (API Key v2). It authenticates the hosted Agent
+# Engine API, Kafka and Schema Registry. The MCP server uses a separate browser
+# login, in Lab 3.
 SN_API_KEY=
 
-# Service-account principal, used as the Kafka SASL username.
+# Your service account's principal, used as the Kafka SASL username.
 # Looks like: <service-account>@<org>.auth.streamnative.cloud
 SN_SERVICE_ACCOUNT=
 
-# Agent Engine registry endpoint (the External one). Host root only, no /v1.
-# Looks like: https://<workspace-host>
+# ------------------------------------------------ from your instance --
+
+# Your agent workspace's external endpoint, with https:// in front. Host root
+# only, no /v1. Looks like: https://<host>
 ORCA_BASE_URL=
 
-# Your team's Kafka cluster and its Schema Registry.
+# Your Kafka cluster's external endpoint, with its port (host:9093), and its
+# schema registry's external endpoint, with https:// in front.
 KAFKA_BOOTSTRAP_SERVERS=
 SCHEMA_REGISTRY_URL=
 
-# StreamNative MCP server for your SQL Workspace (the agent's data tools).
+# Your SQL workspace's MCP route (the agent's data tools):
+# https://mcp.streamnative.cloud/mcp/x/<org>/sqlworkspace.compute.streamnative.io/<SQL workspace>
 SN_MCP_URL=
 
 # MCP authentication: oauth (default) or static_bearer for API-key MCP servers.
@@ -39,15 +45,14 @@ SN_MCP_OAUTH_SCOPE="openid profile email offline_access"
 
 # ------------------------------------------------------------- your choices --
 
-# The Kafka topic name. Injectors and doctor read this value.
-# The SQL files in sql/cloud/ use the default below: edit their quoted
-# "avro.<LOGIN_TOPIC>" source name to match this value before running them in
-# SQL Workspace.
+# The Kafka topic you create and load in Lab 0. The seeder, the injector and the
+# doctor read this value. Your SQL catalog imports the topic as a source with the
+# same name, and the SQL files in sql/cloud/ use the default below: if you change
+# it, change the quoted source name in them too. SQL Workspace does not read .env.
 LOGIN_TOPIC=security.login_events
 
-# The model your agent runs on (served by the event's AI gateway).
+# The model your agent runs on (served by the Agent Engine's AI gateway).
 ORCA_MODEL=claude-sonnet-4-6
 
-# Names your agent, environment, and vault so teammates sharing a workspace
-# don't collide. Defaults to your OS user name.
+# Names your agent, environment, and vault. Defaults to your OS user name.
 PARTICIPANT=

README.md

@@ -25,18 +25,18 @@ The same five labs, on two stacks.
 
 | | [Cloud course](labs/cloud/README.md) | [Local course](labs/local/README.md) |
 |---|---|---|
-| Runs on | StreamNative Cloud: your team's Kafka cluster, SQL Workspace, and a hosted Agent Engine | Your laptop: [Ursa for Kafka](https://openlakestream.org/docs/ursa-for-kafka), [RisingWave](https://risingwave.com), and the Orca Agent Engine (`ork local`) |
-| You need | A team card, handed out at the hackathon | Docker and an Anthropic API key |
-| Time | About 30 minutes | About 45 minutes, plus image downloads |
+| Runs on | StreamNative Cloud: your own instance, with a Kafka cluster, a SQL workspace, and an agent workspace | Your laptop: [Ursa for Kafka](https://openlakestream.org/docs/ursa-for-kafka), [RisingWave](https://risingwave.com), and the Orca Agent Engine (`ork local`) |
+| You need | A StreamNative Cloud login with your own instance, from the hackathon organizers | Docker and an Anthropic API key |
+| Time | About 40 minutes | About 45 minutes, plus image downloads |
 | Start | [Lab 0: Set up](labs/cloud/00-set-up.md) | [Lab 0: Set up](labs/local/00-set-up.md) |
 
 At the hackathon, take the Cloud course: see
-[Before you arrive](docs/before-you-arrive.md). Without a team card, or to see
-every part run on your own machine, take the Local course.
+[Before you arrive](docs/before-you-arrive.md). Without a StreamNative Cloud
+instance, or to see every part run on your own machine, take the Local course.
 
 ## Pick your path
 
-The agent steps work three ways. Pick one; a teammate can pick another.
+The agent steps work three ways. Pick one.
 
 - **CLI**: the [`ork`](https://github.com/orca-ae/orca-cli) command line
 - **Python**: the [`runorca`](https://pypi.org/project/runorca/) SDK

cli/env.sh

@@ -50,7 +50,7 @@ hello_setup_hint() {
   if [ "$(hello_trim "${TUTORIAL_STACK:-}")" = local ]; then
     printf '%s' "Run local/write-env.sh in the repo root to write .env again (Local course, Lab 0)."
   else
-    printf '%s' "Copy .env.cloud.example to .env in the repo root and fill it in from your team card, or run local/write-env.sh for the Local course."
+    printf '%s' "Copy .env.cloud.example to .env in the repo root and fill it in from your StreamNative Cloud instance (Cloud course, Lab 0), or run local/write-env.sh for the Local course."
   fi
 }
 
@@ -84,7 +84,7 @@ hello_setup() {
     hello_die "jq is not installed. Install it (brew install jq, apt install jq, or winget install jqlang.jq) and try again."
 
   hello_load_dotenv
-  # `cloud`: your team card on StreamNative Cloud. `local`: the stack on your laptop.
+  # `cloud`: your instance on StreamNative Cloud. `local`: the stack on your laptop.
   HELLO_STACK=$(hello_trim "${TUTORIAL_STACK:-cloud}")
   case "$HELLO_STACK" in
     cloud | local) ;;

cli/tests/run.sh

@@ -133,7 +133,7 @@ test_missing_team_card() {
   run "" l1_hello.sh
   check "exits 1 without a team card" [ "$STATUS" -eq 1 ]
   check "names every missing variable, and both ways to get an .env" \
-    err_has "Missing ORCA_BASE_URL, ORCA_MODEL, SN_API_KEY. Copy .env.cloud.example to .env in the repo root and fill it in from your team card, or run local/write-env.sh for the Local course."
+    err_has "Missing ORCA_BASE_URL, ORCA_MODEL, SN_API_KEY. Copy .env.cloud.example to .env in the repo root and fill it in from your StreamNative Cloud instance (Cloud course, Lab 0), or run local/write-env.sh for the Local course."
   check "runs no ork command" [ ! -s "$FAKE_ORK_DIR/calls.log" ]
 }
 

docs/before-you-arrive.md

@@ -1,14 +1,15 @@
 # Before you arrive
 
-Ten minutes at home saves thirty at the event. This page prepares your laptop
-for the [Cloud course](../labs/cloud/README.md), the one you take at the
-hackathon. Pick **one** path; your teammate can pick a different one.
+Twenty minutes at home saves an hour at the event. This page prepares your
+laptop and your StreamNative Cloud instance for the
+[Cloud course](../labs/cloud/README.md), the one you take at the hackathon. Pick
+**one** path.
 
 | Path | Install |
 |---|---|
 | **Python** | Python 3.11 or newer |
 | **TypeScript** | Node.js 20 or newer |
-| **CLI** | Python 3.11+ *or* Node.js 20+, for two helper scripts (the doctor and the data injector) |
+| **CLI** | Python 3.11+ *or* Node.js 20+, for three helper scripts (the doctor, the seeder, and the data injector) |
 
 Everyone also needs:
 
@@ -25,6 +26,9 @@ Everyone also needs:
   server when a choice is needed. The browser flow stores tokens directly in the
   vault.
 - [`jq`](https://jqlang.org/download/), for the checks in every lab.
+- [`snctl`](https://docs.streamnative.io/tools/cli/snctl/snctl-overview) (the
+  StreamNative Cloud CLI): `brew install streamnative/streamnative/snctl`. Lab 0
+  uses it to read your instance's addresses and to create your topic.
 
 ## 1. Get the code
 
@@ -49,7 +53,7 @@ npm install
 ```
 
 **CLI**: install `ork` and `jq`, then set up Python or TypeScript as above for
-the doctor and the injector.
+the doctor, the seeder, and the injector.
 
 ## 3. Check your laptop
 
@@ -58,12 +62,39 @@ python doctor.py --offline         # Python or CLI path
 npm run doctor -- --offline        # TypeScript path
 ```
 
-Every line should say `PASS`. You'll get your **team card** (your credentials
-and endpoints) at the event; [Lab 0](../labs/cloud/00-set-up.md) starts there.
+Every line should say `PASS`.
+
+## 4. Set up your instance
+
+The organizers add you to the hackathon organization on StreamNative Cloud, give
+you an **instance** of your own, and make a **service account** in it. They give
+you its name and its **API key**: keep the key to yourself.
+
+In the StreamNative Cloud console, create three things in your instance, in the
+region the organizers name:
+
+- a **Kafka cluster** (Serverless),
+- an **agent workspace**,
+- a **SQL workspace** that imports your Kafka cluster.
+
+Then log `snctl` in and check that all three are there:
+
+```bash
+snctl config init
+snctl auth login                          # opens your browser
+snctl config set --organization <org>     # the hackathon organization's id, o-...
+snctl get kafkaclusters -o custom-columns=NAME:.metadata.name,INSTANCE:.spec.instanceName
+snctl get workspaces -o custom-columns=NAME:.metadata.name,INSTANCE:.spec.instanceName
+snctl get sqlcatalogs -o custom-columns=NAME:.metadata.name,KAFKA_CLUSTER:.spec.sourceRef.name,SQL_WORKSPACE:.spec.workspaceRef.name
+```
+
+The first two lists have a row for your instance, and the SQL catalog list has a
+row that names your Kafka cluster and your SQL workspace.
+[Lab 0](../labs/cloud/00-set-up.md) reads their addresses into `.env`.
 
 ## Want to try it tonight?
 
 The [Local course](../labs/local/README.md) is the same five labs on your own
-laptop, with no team card: Ursa for Kafka, RisingWave, and the Orca Agent
-Engine in Docker. It needs Docker and an Anthropic API key, and downloads about
-5 GB of images, so start it on a good connection.
+laptop, with nothing on StreamNative Cloud: Ursa for Kafka, RisingWave, and the
+Orca Agent Engine in Docker. It needs Docker and an Anthropic API key, and
+downloads about 5 GB of images, so start it on a good connection.

docs/tutor.md

@@ -49,7 +49,7 @@ last row works in any agent that can read a file.
 Started with no request, the tutor asks three things:
 
 ```text
-1. Course: Cloud (a team card, StreamNative Cloud) or Local (everything on your laptop)?
+1. Course: Cloud (your own instance on StreamNative Cloud) or Local (everything on your laptop)?
 2. Path: CLI, Python, or TypeScript?
 3. What now: start at Lab 0, resume at a lab, quiz me on a lab, or check my setup?
 ```

labs/README.md

@@ -4,13 +4,13 @@ Two courses teach the same five labs on two stacks. Pick one.
 
 | | [Cloud course](cloud/README.md) | [Local course](local/README.md) |
 |---|---|---|
-| Runs on | StreamNative Cloud: your team's Kafka cluster, SQL Workspace, and a hosted Agent Engine | Your laptop: Ursa for Kafka, RisingWave, and the Orca Agent Engine |
-| You need | A team card, handed out at the hackathon | Docker and an Anthropic API key |
-| Time | About 30 minutes | About 45 minutes, plus the image downloads |
-| Take it when | You are at the event | You have no team card, or you want to see every part run |
+| Runs on | StreamNative Cloud: your own instance, with a Kafka cluster, a SQL workspace, and an agent workspace | Your laptop: Ursa for Kafka, RisingWave, and the Orca Agent Engine |
+| You need | A StreamNative Cloud login with your own instance, from the hackathon organizers | Docker and an Anthropic API key |
+| Time | About 40 minutes | About 45 minutes, plus the image downloads |
+| Take it when | You are at the event | You have no StreamNative Cloud instance, or you want to see every part run |
 
 Both courses use the same three paths for the agent steps. Pick one path and stay
-on it; a teammate can pick another.
+on it.
 
 - **CLI**: the [`ork`](https://github.com/orca-ae/orca-cli) command line
 - **Python**: the [`runorca`](https://pypi.org/project/runorca/) SDK