feat(workbench): in-codespace onboarding — banner, welcome doc, two-tabs explainer

.devcontainer/welcome.md

@@ -0,0 +1,57 @@
+# 👋 locus workbench — welcome
+
+You've just clicked the **Launch workbench** button. While this VS Code
+window finishes booting, a **separate browser tab** is opening with the
+workbench UI itself.
+
+## Where's the workbench?
+
+Look for a new tab in your browser at:
+
+> `https://<this-codespace>-5173.app.github.dev`
+
+The actual URL is printed in the terminal panel below (look for the
+🚀 banner). **⌘-click** that URL to open it.
+
+If your browser blocks the auto-popup, just click the URL from the
+terminal. Same destination.
+
+## Two-click flow
+
+1. Open the workbench tab (above).
+2. **Provider settings** → paste an OpenAI or Anthropic API key →
+   pick a tutorial in the sidebar → **Run**.
+
+OCI options in **Provider settings** won't work here — they need a
+local `~/.oci/config` that doesn't exist in this Codespace. Use OpenAI
+or Anthropic for the in-browser path. (For OCI, clone the repo and run
+the workbench locally; see [`docs/workbench.md`](../docs/workbench.md).)
+
+## What's running
+
+Three tiers are auto-started by `postStart.sh`:
+
+| Tier | Port | Process |
+|---|---|---|
+| FastAPI runner (Python) | 8100 | `uvicorn workbench.backend.runner:app` |
+| BFF (Node Express) | 3101 | `tsx watch workbench/bff/src/server.ts` |
+| Vite dev server (web UI) | 5173 | `vite` in `workbench/web/` |
+
+Logs at `/tmp/wb-backend.log`, `/tmp/wb-bff.log`, `/tmp/wb-web.log` —
+the banner terminal panel tails all three.
+
+## Restarting tiers (if they die)
+
+```bash
+# Manually re-fire the lifecycle scripts:
+bash .devcontainer/postStart.sh
+```
+
+## Further reading
+
+- [`docs/workbench.md`](../docs/workbench.md) — the public workbench page
+- [`docs/index.md`](../docs/index.md) — locus SDK landing page
+- [`workbench/README.md`](../workbench/README.md) — three-tier
+  architecture explained
+- [`examples/`](../examples/) — 55 progressive tutorials, all runnable
+  from the workbench

.devcontainer/workbench-banner.sh

@@ -0,0 +1,64 @@
+#!/usr/bin/env bash
+# Show a clear "your workbench is here" banner the moment Vite binds.
+#
+# Why this exists: when a developer clicks the docs `Launch workbench`
+# button, GitHub Codespaces opens VS Code Web in their browser. The
+# devcontainer's `5173.onAutoForward: openBrowserOnce` triggers a SECOND
+# tab with the workbench UI — but popup blockers (Safari, locked-down
+# browsers) often silently swallow that tab, leaving the developer
+# staring at VS Code with no idea where the playground is. This task
+# fires on workspace open, waits for Vite, then prints a Cmd-clickable
+# URL in a dedicated terminal panel that VS Code reveals automatically.
+#
+# The companion `welcome.md` is also opened as an editor tab below so
+# the URL is visible in two places: the terminal banner and the
+# welcome doc.
+
+set -euo pipefail
+
+# Only meaningful in a Codespace (where CODESPACE_NAME is exported by
+# GitHub). On a local devcontainer / Docker run, fall back to localhost.
+if [ -n "${CODESPACE_NAME:-}" ]; then
+  URL="https://${CODESPACE_NAME}-5173.app.github.dev"
+else
+  URL="http://localhost:5173"
+fi
+
+# Open the welcome doc beside the editor. `code` is in PATH inside VS
+# Code Codespaces and is a no-op (but non-fatal) elsewhere.
+if command -v code >/dev/null 2>&1; then
+  code .devcontainer/welcome.md 2>/dev/null || true
+fi
+
+# Poll until Vite binds (postStart launches it in detached sessions —
+# allow up to ~3 min for first-time codespace boot through pip + npm).
+echo
+echo "Waiting for Vite to bind on :5173..."
+for _ in $(seq 1 60); do
+  if curl -sf http://127.0.0.1:5173/ > /dev/null 2>&1; then
+    break
+  fi
+  sleep 3
+done
+
+cat <<EOF
+
+
+  ────────────────────────────────────────────────────────────
+   🚀  locus workbench is ready
+
+   ▸  ${URL}
+
+   ⌘-click the URL above to open the workbench in a new tab.
+   GitHub may have already auto-opened it; if not, this is it.
+
+   Then: Provider settings → paste an OpenAI or Anthropic key
+         → pick a tutorial in the sidebar → Run.
+  ────────────────────────────────────────────────────────────
+
+
+EOF
+
+# Keep the panel alive so the URL stays on screen. Tail the three tier
+# logs at low frequency so the developer can see liveness without spam.
+exec tail -n 0 -F /tmp/wb-backend.log /tmp/wb-bff.log /tmp/wb-web.log 2>/dev/null

.vscode/tasks.json

@@ -0,0 +1,25 @@
+{
+  "version": "2.0.0",
+  "tasks": [
+    {
+      "label": "→ Workbench banner",
+      "type": "shell",
+      "command": "bash",
+      "args": ["-c", ".devcontainer/workbench-banner.sh"],
+      "runOptions": {
+        "runOn": "folderOpen"
+      },
+      "presentation": {
+        "echo": true,
+        "reveal": "always",
+        "panel": "dedicated",
+        "focus": false,
+        "close": false,
+        "showReuseMessage": false,
+        "clear": false
+      },
+      "isBackground": true,
+      "problemMatcher": []
+    }
+  ]
+}

docs/workbench.md

@@ -86,15 +86,22 @@ hit the layer cache.
 
 1. **Cold start** — GitHub builds the container from
    `.devcontainer/devcontainer.json` (Python 3.12 + Node 20). First
-   boot runs `postCreate.sh` to `pip install -e ".[dev]"` and
-   `npm install` both workbench projects. ~2 minutes.
-2. **Auto-boot** — `postStart.sh` backgrounds the three tiers:
-   `uvicorn runner:app` on `:8100`, `npm run dev` (Express) on
+   boot runs `postCreate.sh` to `pip install -e ".[dev,llm]"` plus
+   `fastapi` + `python-multipart`, and `npm install` both workbench
+   projects against the public npm registry. ~2 minutes.
+2. **Two tabs open** — GitHub Codespaces opens a **VS Code Web** tab
+   first (the editor session that owns the container). When Vite
+   binds on `:5173`, a **second tab** pops automatically with the
+   workbench UI itself (`https://<codespace>-5173.app.github.dev`)
+   per `5173.onAutoForward: openBrowserOnce`. **The workbench is the
+   second tab, not VS Code.** If your browser blocks the popup, the
+   VS Code terminal panel shows a clearly-labelled `🚀 locus
+   workbench is ready` banner with a ⌘-clickable URL — same
+   destination.
+3. **Auto-boot** — `postStart.sh` backgrounds the three tiers in
+   detached `setsid` sessions so they survive after the lifecycle hook
+   exits: `uvicorn runner:app` on `:8100`, `npm run dev` (Express) on
    `:3101`, `npm run dev` (Vite) on `:5173`.
-3. **Auto-open** — `devcontainer.json` has
-   `5173.onAutoForward: openBrowserOnce`, so the workbench UI pops in
-   a new tab as soon as Vite binds. No clicking around in the Ports
-   panel.
 4. **Run a pattern** — *Provider settings* → paste an OpenAI or
    Anthropic key → pick a tutorial → **Run**.