Document building the team card from the environment sheet

Teams are given access to the environment sheet that the organizers keep
and build their team card themselves, so the team-card Lab 0 now says
how.

- Step 2 maps six columns of a team row to .env lines, gives the console
  steps for creating an API key for the team service account, and shows
  a finished card with placeholders.
- The READMEs, .env.cloud.example and docs/before-you-arrive.md describe
  a team environment and its sheet instead of a card that is handed over.
- Troubleshooting: with a team card, a rejected key is replaced by
  creating a new one.
- The tutor asks whether the team has a row in the environment sheet.
- What was run: steps 2 and 3 against a test instance with the seven
  lines filled in. The API key steps follow the labels of the console and
  were not clicked through.

Author: sijie

.env.cloud.example

@@ -4,7 +4,8 @@
 #   cp .env.cloud.example .env
 #
 # labs/cloud/00-set-up.md, step 2, has the snctl command for each address.
-# With a team card, every value comes from the card instead:
+# In an environment the organizers created for your team, the values come from
+# your row in their environment sheet, and you create the API key yourself:
 # labs/cloud/00-set-up-team-card.md, step 2.
 # (The Local course writes its own .env: see labs/local/00-set-up.md.)
 

README.md

@@ -26,7 +26,7 @@ The same five labs, on two stacks.
 | | [Cloud course](labs/cloud/README.md) | [Local course](labs/local/README.md) |
 |---|---|---|
 | 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 from the hackathon organizers, with a team card or an instance of your own | Docker and an Anthropic API key |
+| You need | A StreamNative Cloud login from the hackathon organizers, with a team environment they created or an instance of your own | 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), or [from a team card](labs/cloud/00-set-up-team-card.md) | [Lab 0: Set up](labs/local/00-set-up.md) |
 

docs/before-you-arrive.md

@@ -30,8 +30,8 @@ Everyone also needs:
 - [`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. With a
-  team card (step 4) you do not need it.
+  uses it to read your instance's addresses and to create your topic. In an
+  environment the organizers created for your team (step 4) you do not need it.
 
 ## 1. Get the code
 
@@ -74,12 +74,12 @@ Every line should say `PASS`.
 
 ## 4. Set up your instance
 
-**Getting a team card?** If the organizers told you that your team's
-environment is created for you, skip this step and create nothing in the
-console: your Kafka cluster, SQL workspace, and agent workspace already exist.
-Your team card has their addresses and an API key, and
-[Lab 0: Set up from a team card](../labs/cloud/00-set-up-team-card.md) starts
-from it.
+**Did the organizers create your team's environment?** Then skip this step and
+create nothing in the console: your Kafka cluster, SQL workspace, and agent
+workspace already exist. The organizers share an environment sheet with a row
+for your team, and
+[Lab 0: Set up from a team card](../labs/cloud/00-set-up-team-card.md) turns
+that row into your `.env`.
 
 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

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 (on StreamNative Cloud, with a team card from the organizers or with your own instance: say which) or Local (everything on your laptop)?
+1. Course: Cloud (on StreamNative Cloud, in a team environment the organizers created or in your own instance: say which) 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?
 ```
@@ -59,7 +59,7 @@ Started with no request, the tutor asks three things:
 | You want to | Say |
 |---|---|
 | Take a course from the start | `Start the Cloud course on the Python path.` |
-| Start from a team card | `Start the Cloud course on the Python path. I have a team card.` |
+| Start in a team environment | `Start the Cloud course on the Python path. My team has a row in the organizers' environment sheet.` |
 | Pick up where you stopped | `Resume the Local course at Lab 3. I'm on TypeScript.` |
 | Be quizzed | `Quiz me on Lab 2.` |
 | Find out why something fails | `Check my setup.` Or paste the error. |

labs/README.md

@@ -5,7 +5,7 @@ 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 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 from the hackathon organizers, with a team card or an instance of your own | Docker and an Anthropic API key |
+| You need | A StreamNative Cloud login from the hackathon organizers, with a team environment they created or an instance of your own | 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 |
 

labs/cloud/00-set-up-team-card.md

@@ -1,23 +1,28 @@
 # Lab 0: Set up from a team card
 
-**Cloud course** · 5 minutes, plus 5 on your own · CLI, Python, or TypeScript
+**Cloud course** · 8 minutes, plus 5 on your own · CLI, Python, or TypeScript
 
-You put your team card in `.env`, load the login stream into your team's Kafka
-cluster, and run the doctor. When this lab is done, the Agent Engine, Kafka,
-and Schema Registry on your card all answer, and your topic holds 246 logins.
+The organizers created an environment for your team on StreamNative Cloud. You
+build your **team card** from it, put it in `.env`, load the login stream into
+your team's Kafka cluster, and run the doctor. When this lab is done, the Agent
+Engine, Kafka, and Schema Registry on your card all answer, and your topic
+holds 246 logins.
 
-No team card? [Lab 0: Set up](00-set-up.md) starts from an instance of your own
-instead. Both end in the same place, and Lab 1 is the same after either.
+Your team is not in the organizers' environment sheet?
+[Lab 0: Set up](00-set-up.md) starts from an instance of your own instead. Both
+end in the same place, and Lab 1 is the same after either.
 
 ## Before you start
 
-- You have your **team card** from the organizers: an **API key**, and the
-  addresses of the environment they created for your team on StreamNative
-  Cloud. That environment is a Kafka cluster, a SQL workspace that imports it,
-  an agent workspace, and the service account the key belongs to. Everything on
-  the card already exists: you create nothing, and you do not need `snctl`.
-- You can log in to StreamNative Cloud, and the organizers added your login to
-  your team's environment. This lab does not use that login; Labs 2 and 3 do.
+- The organizers created your team's environment and shared the **environment
+  sheet** with you. On its **Team Environments** tab, one row is your team's:
+  the names and addresses of a Kafka cluster, a SQL workspace that imports it,
+  an agent workspace, and a service account. All of it already exists. In this
+  lab you create one thing, an API key, and you do not need `snctl`.
+- You know your team's number: it is the **Team ID** of your row.
+- You can log in to the StreamNative Cloud console, in the organization your
+  row names. You create your API key there in step 2, and Labs 2 and 3 use the
+  same login.
 - You cloned this repository and opened a terminal in it. The terminal runs
   `bash`: on Windows that is WSL or Git Bash, on every path, because the checks
   are `bash` commands.
@@ -67,38 +72,73 @@ PASS  jq                               found
 All good: you're ready.
 ```
 
-## Step 2: Fill in `.env` from your team card
+## Step 2: Build your team card in `.env`
+
+Your team card is your team's row in the environment sheet, plus an API key
+that you create. `.env` is where you write it down.
 
 Open a second terminal at the repository root and copy the template:
 
 ```bash
 cp .env.cloud.example .env
 ```
 
-`.env` is git-ignored. It will hold your team's key: do not commit it or paste
-it anywhere. Give each of these lines its value from the card:
+`.env` is git-ignored. It will hold your key: do not commit it or paste it
+anywhere.
+
+**From the sheet.** Open the environment sheet on the **Team Environments** tab
+and find the row with your **Team ID**. Six lines of `.env` come from that row:
 
-| `.env` line | On your card | Write it as |
+| `.env` line | Column in your row | Write it as |
 |---|---|---|
-| `SN_API_KEY` | API key | the raw key, with no `token:` in front |
-| `SN_SERVICE_ACCOUNT` | Service account | `<name>@<org>.auth.streamnative.cloud`. If the card has only the name, add the rest, with the organization id from the card (`o-...`) |
-| `ORCA_BASE_URL` | Agent workspace endpoint | `https://` and the host, with no `/v1` |
-| `KAFKA_BOOTSTRAP_SERVERS` | Broker URL | the host and its port, `:9093` |
-| `SCHEMA_REGISTRY_URL` | Schema registry URL | `https://` and the host |
-| `SN_MCP_URL` | SQL workspace MCP endpoint | `https://mcp.streamnative.cloud/mcp/x/<org>/sqlworkspace.compute.streamnative.io/<SQL workspace>` |
-| `SN_SQL_DATABASE` | SQL database | as given. It is the name of your SQL catalog, not of your SQL workspace |
-
-If your card already is a list of `NAME=value` lines, paste each one over the
-empty line with the same name.
-
-`SN_SQL_DATABASE` is the database you use in Lab 2 and the agent targets in
-Labs 3 and 4. Leave the other lines as they are: the MCP server uses a separate
-browser login in Lab 3, so `SN_MCP_AUTH=oauth` stays, and `SN_MCP_OAUTH_ISSUER`
-stays empty.
-
-**Two people share one team card.** Your teammate fills in the same values, and
-you both work in the same Kafka cluster and the same SQL database. Your agents
-stay apart: each is named after its owner's OS user name, like
+| `SN_SERVICE_ACCOUNT` | **Service Account**, with **StreamNative Cloud Organization** | `<Service Account>@<Organization>.auth.streamnative.cloud`. A cell that already ends in `.auth.streamnative.cloud` goes in as it is |
+| `ORCA_BASE_URL` | **Agent Workspace Endpoint** | `https://` and the host, with no `/v1` |
+| `KAFKA_BOOTSTRAP_SERVERS` | **Broker URL** | as it is: the host and its port, `:9093` |
+| `SCHEMA_REGISTRY_URL` | **Schema Registry URL** | as it is, with `https://` |
+| `SN_MCP_URL` | **SQL Workspace MCP Endpoint** | as it is |
+| `SN_SQL_DATABASE` | **SQL Database** | as it is. It is the database you open in Lab 2, and it is not your SQL workspace's name |
+
+A cell you need is empty? Ask a facilitator. One value you can build yourself:
+the MCP endpoint is
+`https://mcp.streamnative.cloud/mcp/x/<Organization>/sqlworkspace.compute.streamnative.io/<SQL Workspace Name>`,
+from two other cells of your row.
+
+**Your API key.** The sheet holds no keys. You create one in the StreamNative
+Cloud console, for the service account in your row:
+
+1. Log in to the console, in the organization your row names.
+2. Open the organization's **Settings**. Under **Access & Control**, click
+   **Service Accounts**, then click your team's service account.
+3. Click **Create API key**. Give the key a **Name** that nobody else in the
+   organization uses, in lowercase letters, digits, and dashes: your team and
+   your name work, such as `team07-ana`. Leave **Expiration** at 30 days, and
+   click **Create**.
+4. The next window shows the key, once. Click **Copy**, paste the key into
+   `.env` as `SN_API_KEY` with nothing in front of it, then click **Close**. If
+   you lose the key, create another.
+
+If **Create API key** is greyed out, your login may not create keys: ask a
+facilitator.
+
+Leave the other lines as they are: the MCP server uses a separate browser login
+in Lab 3, so `SN_MCP_AUTH=oauth` stays, and `SN_MCP_OAUTH_ISSUER` stays empty.
+
+Your finished card has these seven lines filled in:
+
+```text
+SN_API_KEY=<the key you copied>
+SN_SERVICE_ACCOUNT=<service account>@<organization>.auth.streamnative.cloud
+ORCA_BASE_URL=https://<agent workspace host>
+KAFKA_BOOTSTRAP_SERVERS=<broker host>:9093
+SCHEMA_REGISTRY_URL=https://<schema registry host>
+SN_MCP_URL=https://mcp.streamnative.cloud/mcp/x/<organization>/sqlworkspace.compute.streamnative.io/<SQL workspace>
+SN_SQL_DATABASE=<SQL database>
+```
+
+**Two people share one environment.** Your teammate fills in the same six lines
+from the same row, and can create a key of their own for the same service
+account. You both work in the same Kafka cluster and the same SQL database.
+Your agents stay apart: each is named after its owner's OS user name, like
 `hello-agent-ana`. If the two of you have the same user name, each set
 `PARTICIPANT` in `.env` to a name of your own. In Lab 2 the view and the table
 are created once for the team: if your teammate got there first, the `CREATE`
@@ -190,7 +230,7 @@ Still failing after two tries? Raise your hand, or see
 
 - A. Fix it now: the doctor has to print only `PASS`.
 - B. Nothing yet: Lab 3 does the browser login this check waits for.
-- C. Ask for a new team card.
+- C. Create a new API key.
 
 <details>
 <summary>Answer</summary>
@@ -263,8 +303,9 @@ Engine check, tells you the exact value to use, and ends with
 
 ## Recap
 
-- `.env` holds your team card: the addresses of your team's environment and its
-  key. It is git-ignored.
+- `.env` holds your team card: six values from your team's row in the
+  environment sheet, and an API key you created for your team's service
+  account. It is git-ignored.
 - Your team shares that environment. The login stream is loaded once, and the
   seeder refuses a second copy.
 - The doctor checks each service on the card and prints the fix for a failure.

labs/cloud/README.md

@@ -25,7 +25,7 @@ flowchart LR
 | Lab | Time | Where | You | The idea |
 |---|---|---|---|---|
 | [0. Set up](00-set-up.md) | 10 min | terminal | Fill in `.env` from your instance, load the topic, run the doctor | Check service access before you build on it |
-| or [0. Set up from a team card](00-set-up-team-card.md) | 5 min | terminal | Fill in `.env` from your team card, load the topic, run the doctor | The same, when the organizers created your environment |
+| or [0. Set up from a team card](00-set-up-team-card.md) | 8 min | terminal | Build your team card from the organizers' environment sheet, load the topic, run the doctor | The same, when the organizers created your environment |
 | [1. Hello, agent](01-hello-agent.md) | 5 min | CLI / Python / TS | Create an agent and chat | Agent, environment, session, events |
 | [2. Hello, streaming SQL](02-streaming-sql.md) | 8 min | SQL Workspace | Build a materialized view over the topic | Context that keeps itself fresh |
 | [3. Agent + live context](03-live-context.md) | 9 min | CLI / Python / TS | Give the agent SQL tools, inject new data | The answer changes with the data |
@@ -44,8 +44,9 @@ your own.
 - One path installed, plus `ork`, `jq`, and `snctl`. All of this is in
   [Before you arrive](../../docs/before-you-arrive.md).
 
-**Have a team card?** Then the organizers created all of this for your team,
-and the card has its addresses and an API key. You need only your login, one
+**Is your team in the organizers' environment sheet?** Then they created all
+of this for your team. Your team's row has the addresses, and you create an API
+key yourself: together they are your team card. You need only your login, one
 path, `ork`, and `jq`, and you start with
 [Lab 0: Set up from a team card](00-set-up-team-card.md).
 
@@ -67,14 +68,15 @@ cluster was Serverless; the SQL workspace ran RisingWave 3.1.0-alpha.
   Python path. On the TypeScript path, the doctor, and the seeder against the
   topic once it was loaded.
 - **Lab 0 from a team card**: added on 6 October 2026 and run that day against
-  the same test instance, from a card of ready-made `NAME=value` lines. On the
+  the same test instance, with the seven lines of step 2 filled in. On the
   Python path: every step and check, and the failing doctor run its solution
   shows. On the TypeScript path, and with the CLI column's commands: the doctor
   and the seeder. The topic was loaded already (274 events, after earlier Lab 3
-  runs), so the seeder printed its "already holds" line each time. The card had
-  no `SN_SQL_DATABASE` line; nothing in Lab 0 reads that value. Not run from
-  this page: the seeder on an empty topic, a card of labeled values, and an
-  environment the organizers created.
+  runs), so the seeder printed its "already holds" line each time. Nothing in
+  Lab 0 reads `SN_SQL_DATABASE`. Not run from this page: reading the values
+  from an environment sheet, creating the API key (its steps follow the
+  console's labels as of 3 October 2026; the key used was an existing one), the
+  seeder on an empty topic, and an environment the organizers created.
 - **Lab 2**: every statement and check, through `psql`. The console was not
   used.
 - **Labs 1, 3 and 4**: every step and check, on all three paths, with the model

labs/cloud/troubleshooting.md

@@ -14,7 +14,7 @@ Still stuck after two tries? Raise your hand.
 | Symptom | Fix |
 |---|---|
 | `pip install -r requirements.txt`: `No matching distribution found for runorca==0.3.0` | The `python3` that made your virtual environment is older than the course needs: on macOS, Apple's own is 3.9. Install Python 3.11 or newer, then make the environment again with it. In `python/`: `rm -rf .venv`, then the install commands from Lab 0 with that Python's name in place of `python3`, for example `python3.13 -m venv .venv`. |
-| Doctor: `Agent Engine HTTP 401/403` | The key was rejected. A key created before its permissions must be re-created: ask a facilitator. |
+| Doctor: `Agent Engine HTTP 401/403` | The key was rejected. A key created before its permissions must be re-created. With a team card, create a new key yourself (Lab 0, step 2) and put it in `SN_API_KEY`; otherwise ask a facilitator. |
 | Doctor: `Kafka ... authentication` | `SN_SERVICE_ACCOUNT` must be the full principal, `<name>@<org>.auth.streamnative.cloud`; `SN_API_KEY` is the raw key. |
 | Doctor: `Kafka   security.login_events: not found` | The topic is not there yet. Create it and load it: Lab 0, step 3. |
 | Doctor: `Schema Registry ... not found` | The schema is registered when you load the topic: Lab 0, step 3. |