Split the tutorial into Cloud and Local lab courses, add a tutor skill (#3)

The single README walkthrough becomes two linear lab courses in the shape
of the Orca University labs: one file per lab, each with "Before you
start", three or four steps with a check, a quiz, a "Try it yourself"
task, a clean-up where one is needed, and a recap.

- labs/cloud: the course the hackathon runs, on a team card. Its lab
  scripts, agent definitions and turn loop are the ones main had.
- labs/local: the whole stack on a laptop. local/compose.yaml runs Ursa
  for Kafka (a diskless topic), Oxia, RustFS, Karapace, RisingWave and
  RisingWave's MCP server. local/engine.sh starts `ork local` with the AI
  Gateway and lets the gateway reach the MCP server; write-env.sh,
  sql.sh and down.sh do the rest.
- TUTORIAL_STACK=cloud|local in .env picks the agent definitions
  (agent/<stack>/), the SQL (sql/<stack>/), Kafka auth, the vault and
  the state file, on all three paths.
- Python and TypeScript send the message before they open the event
  stream on the local stack only: `ork local` answers a stream opened on
  a quiet session at its next keep-alive, 15 s later. A team card keeps
  main's order.
- Seeders replay data/login_events.jsonl into an empty topic; lab-ork
  runs every check with the saved ids filled in.
- skills/data-agent-tutor walks a learner through a course one step at a
  time; docs/tutor.md says how to start it.
- scripts/check-labs.sh lints the labs' structure and links; CI gains
  `local` and `labs` jobs.

The Local course was run end to end with the model answering, on the
CLI, Python and TypeScript paths. Nothing that needs a team card was run
for this change.

Author: sijie

.agents/skills/data-agent-tutor

@@ -0,0 +1 @@
+../../skills/data-agent-tutor

.claude-plugin/marketplace.json

@@ -0,0 +1,21 @@
+{
+  "name": "dataplusagent-hackathon-tutorial",
+  "owner": {
+    "name": "StreamNative"
+  },
+  "metadata": {
+    "description": "The tutor for the Data + Agent Hackathon hello-world labs",
+    "version": "0.1.0"
+  },
+  "plugins": [
+    {
+      "name": "data-agent-tutor",
+      "description": "A tutor that walks you through the Data + Agent Hackathon labs one step at a time, checks your work with you, and quizzes you",
+      "source": "./",
+      "strict": false,
+      "skills": [
+        "./skills/data-agent-tutor"
+      ]
+    }
+  ]
+}

.claude/settings.json

@@ -0,0 +1,10 @@
+{
+  "permissions": {
+    "deny": [
+      "Read(/.env)",
+      "Read(/.env.cloud)",
+      "Read(/.env.local)",
+      "Read(/.lab/**)"
+    ]
+  }
+}

.claude/skills/data-agent-tutor

@@ -0,0 +1 @@
+../../skills/data-agent-tutor

.env.example .env.cloud.example.env.example renamed to .env.cloud.example

@@ -1,5 +1,9 @@
-# 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 paste the
+# values from your team card. .env is git-ignored: never commit it.
+#
+#   cp .env.cloud.example .env
+#
+# (The Local course writes its own .env: see labs/local/00-set-up.md.)
 
 # ---------------------------------------------------------------- team card --
 
@@ -11,11 +15,6 @@ SN_API_KEY=
 # Looks like: <service-account>@<org>.auth.streamnative.cloud
 SN_SERVICE_ACCOUNT=
 
-# Optional separate Registry workspace key for ork local (sent as x-api-key).
-# Leave empty for a hosted team card; SN_API_KEY then authenticates Agent Engine.
-# This key does not authenticate Kafka, Schema Registry, or StreamNative MCP.
-ORCA_API_KEY=
-
 # Agent Engine registry endpoint (the External one). Host root only, no /v1.
 # Looks like: https://<workspace-host>
 ORCA_BASE_URL=
@@ -28,9 +27,8 @@ SCHEMA_REGISTRY_URL=
 SN_MCP_URL=
 
 # MCP authentication: oauth (default) or static_bearer for API-key MCP servers.
-# All three tutorial paths call ork for the first OAuth login, then reuse the
-# credential stored in the vault. Install ork with the OAuth discovery support
-# from orca-cli PR #8 (or current main).
+# All three paths call ork for the first OAuth login, then reuse the
+# credential stored in the vault. Needs ork v0.6.0 or newer.
 SN_MCP_AUTH=oauth
 
 # Optional authorization server selection. Leave empty for automatic discovery.
@@ -42,8 +40,9 @@ SN_MCP_OAUTH_SCOPE="openid profile email offline_access"
 # ------------------------------------------------------------- your choices --
 
 # The Kafka topic name. Injectors and doctor read this value.
-# L2 SQL files use the default below: edit their quoted "avro.<LOGIN_TOPIC>"
-# source name to match this value before running them in SQL Workspace.
+# 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.
 LOGIN_TOPIC=security.login_events
 
 # The model your agent runs on (served by the event's AI gateway).

.env.local.example

@@ -0,0 +1,29 @@
+# The Local course: you do not fill this in by hand. local/write-env.sh writes
+# .env for you, with the key your Agent Engine generated (labs/local/00-set-up.md).
+# This file shows what it writes. .env is git-ignored: never commit it.
+
+# Tells every script that the stack is the one on your laptop.
+TUTORIAL_STACK=local
+
+# The Agent Engine that `ork local` runs, and the workspace key it generated.
+ORCA_BASE_URL=http://127.0.0.1:8080
+ORCA_API_KEY=
+
+# Ursa for Kafka and its schema registry, as your terminal reaches them.
+KAFKA_BOOTSTRAP_SERVERS=127.0.0.1:29092
+SCHEMA_REGISTRY_URL=http://127.0.0.1:18081
+
+# RisingWave's MCP server. The first address is the one your agent's definition
+# carries: the AI Gateway reaches the server by that name. The second is the same
+# server from your terminal, for the doctor.
+RW_MCP_URL=http://risingwave-mcp:8000/mcp
+RW_MCP_LOCAL_URL=http://127.0.0.1:8000/mcp
+
+# The Kafka topic the injector writes to and RisingWave reads.
+LOGIN_TOPIC=security.login_events
+
+# The model your agent runs on. Your provider key must be able to use it.
+ORCA_MODEL=claude-sonnet-4-6
+
+# Names your agent and environment. Defaults to your OS user name.
+PARTICIPANT=

.github/workflows/ci.yml

@@ -42,9 +42,27 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - run: shellcheck cli/*.sh cli/tests/*.sh cli/tests/fake-ork
+      - run: shellcheck cli/*.sh cli/tests/*.sh cli/tests/fake-ork lab-ork
       - run: cli/tests/run.sh
 
+  local:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: shellcheck local/*.sh local/tests/*.sh
+      - run: local/tests/run.sh
+      - name: The Compose file is valid
+        run: docker compose -f local/compose.yaml config -q
+
+  labs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: shellcheck scripts/*.sh scripts/tests/*.sh
+      - run: scripts/tests/run.sh
+      - name: Every lab has its steps, checks, quiz and solution, and every link resolves
+        run: scripts/check-labs.sh
+
   no-credentials:
     runs-on: ubuntu-latest
     steps:

.gitignore

@@ -1,11 +1,17 @@
-# Secrets: your team card lives here. Never commit it.
+# Secrets: your team card (or your local stack's key) lives here. Never commit it.
 .env
 .env.*
-!.env.example
+!.env.*.example
 
 # Local state (agent/environment/vault ids per participant)
 .orca-state/
 
+# The Local course's Agent Engine data: `ork local` keeps its keys here.
+.lab/
+
+# Claude Code worktrees
+.claude/worktrees/
+
 # Python
 .venv/
 __pycache__/