@stemtrooper/learningcode 0.1.0 → 0.2.1

package/README.md

@@ -47,6 +47,100 @@ Because Spark's limits are the design constraint, not the model:
 Stock Pi does not know `/v1/me/quota` or `/v1/queue` exist. That gap is the whole
 reason this wrapper exists.
 
+## Banner
+
+The LEARNINGCODE block banner replaces Pi's header at startup:
+
+```
+  ██╗     ███████╗ █████╗ ██████╗ ███╗   ██╗██╗███╗   ██╗ ██████╗  ██████╗ ██████╗ ██████╗ ███████╗
+  ██║     ██╔════╝██╔══██╗██╔══██╗████╗  ██║██║████╗  ██║██╔════╝ ██╔════╝██╔═══██╗██╔══██╗██╔════╝
+  ██║     █████╗  ███████║██████╔╝██╔██╗ ██║██║██╔██╗ ██║██║  ███╗██║     ██║   ██║██║  ██║█████╗
+  ██║     ██╔══╝  ██╔══██║██╔══██╗██║╚██╗██║██║██║╚██╗██║██║   ██║██║     ██║   ██║██║  ██║██╔══╝
+  ███████╗███████╗██║  ██║██║  ██║██║ ╚████║██║██║ ╚████║╚██████╔╝╚██████╗╚██████╔╝██████╔╝███████╗
+  ╚══════╝╚══════╝╚═╝  ╚═╝╚═╝  ╚═╝╚═╝  ╚═══╝╚═╝╚═╝  ╚═══╝ ╚═════╝  ╚═════╝ ╚═════╝ ╚═════╝ ╚══════╝
+  ═════════════════════════════════════════════════════════════════════════════════════════════════
+  The Learning Curve · Sarawak
+  /help commands · /quota today's spend · /hotkeys keys
+```
+
+The figlet "ANSI Shadow" face, 97 columns wide, kept verbatim because the
+double-line box characters only align if every row keeps its exact offset.
+
+Colour comes from the active theme, so it stays legible in light and dark.
+
+**It needs a 99 column terminal.** Below that it collapses to a wordmark,
+rather than drawing art that would be clipped into something that looks broken.
+An 80 column terminal will show the compact form, so widen the window or reduce
+the art.
+
+It installs via `ctx.ui.setHeader`, the supported way to brand a fork.
+
+## Other providers
+
+Any `--model` other than `tlc-spark/...` skips the Spark token and the Spark
+health check, so you can work while Spark is down:
+
+```bash
+export OPENCODE_API_KEY=...
+learningcode --model opencode-go/glm-5.3-flash
+```
+
+**OpenCode Zen is excluded.** Zen and Go share one `OPENCODE_API_KEY`, so leaving
+that variable in place authenticates both and exposes Zen's 111 pay-per-use models
+alongside the 29 a Go subscription covers, at up to $20/M output. learningcode
+moves the key into Pi's `auth.json` under `opencode-go` alone, which leaves Zen
+credential-less so it never registers. Set `LEARNINGCODE_ALLOW_ZEN=1` to opt in.
+
+## Theme
+
+Two TLC themes ship with the package and are seeded into
+`~/.learningcode/agent/themes/` on first run:
+
+| Theme | Accent | Sampled from |
+|---|---|---|
+| `tlc-dark` | `#29c8f2` | `TLC_BLACKBGND.png` |
+| `tlc-light` | `#0dacd6` | `TLC_WHITEBGND.png` |
+
+The values are read out of the logo pixels, not eyeballed. The logo ships two
+cyans because the darker one has to hold contrast on a white field, which maps
+exactly onto Pi's light/dark split.
+
+A seeded theme is **never overwritten**, so an edit survives upgrades. Override
+the default with `--theme`, or `LEARNINGCODE_THEME=tlc-light`. To try Pi's own:
+
+```bash
+learningcode --theme dark
+```
+
+28 of Pi's 56 colour tokens are re-tinted: the accent, borders, greys, markdown,
+syntax highlighting, diff colours, selected backgrounds, and the thinking-level
+ramp. Semantic colours (red, green, yellow) are left alone, because those mean
+error, success and warning rather than anything about the brand. The thinking ramp
+runs grey to cyan and keeps red at the top, where it still means "this is getting
+expensive".
+
+The banner does **not** follow the theme. It uses the brand cyan directly, the way
+Pi's own logo does, because a wordmark that changes colour with whatever theme is
+active stops being a wordmark. It picks the right one of the two cyans from the
+terminal's colour mode.
+
+## Footer
+
+While connected to Spark, a footer shows today's token spend:
+
+```
+  █████░░░░░ 50%  125k / 250k today
+```
+
+Spark's quota endpoint is not part of the OpenAI API, so no stock harness shows
+this. It polls at most every two minutes, since Spark allows one active
+generation per student and a per-turn refresh would add latency to the thing the
+student is waiting on. When AI is switched off for an account the footer says so
+instead of showing a bar.
+
+Off Spark, or with no token, it says so rather than drawing an empty bar that would
+read as "you have spent nothing".
+
 ## Configuration
 
 `~/.learningcode/agent/models.json` is created on first run and **never

package/assets/themes/tlc-dark.json

@@ -0,0 +1,79 @@
+{
+  "$schema": "https://raw.githubusercontent.com/earendil-works/pi/main/packages/coding-agent/src/modes/interactive/theme/theme-schema.json",
+  "name": "TLC dark",
+  "appearance": "dark",
+  "vars": {
+    "text": "okhsl(0 0% 92%)",
+    "muted": "okhsl(205 8% 68%)",
+    "violet": "okhsl(295 50% 67%)",
+    "blue": "okhsl(205 14% 62%)",
+    "green": "okhsl(159 59% 67%)",
+    "red": "okhsl(20 72% 67%)",
+    "yellow": "okhsl(83 88% 67%)",
+    "blueBg": "okhsl(196 48% 18%)",
+    "cyan": "#29c8f2"
+  },
+  "colors": {
+    "accent": "#29c8f2",
+    "border": "okhsl(205 12% 50%)",
+    "borderAccent": "#29c8f2",
+    "borderMuted": "okhsl(205 10% 36%)",
+    "success": "green",
+    "error": "red",
+    "warning": "yellow",
+    "muted": "okhsl(205 8% 68%)",
+    "dim": "okhsl(205 8% 56%)",
+    "text": "okhsl(0 0% 92%)",
+    "thinkingText": "okhsl(196 30% 70%)",
+    "selectedBg": "okhsl(196 48% 18%)",
+    "scrollbarTrack": "okhsl(205 10% 20%)",
+    "scrollbarThumb": "okhsl(205 10% 40%)",
+    "searchMatchBg": "okhsl(53 51% 24%)",
+    "searchMatchText": "muted",
+    "userMessageBg": "okhsl(196 48% 18%)",
+    "userMessageText": "text",
+    "customMessageBg": "okhsl(196 38% 16%)",
+    "customMessageText": "muted",
+    "customMessageLabel": "#29c8f2",
+    "toolPendingBg": "okhsl(229 5% 24%)",
+    "toolSuccessBg": "okhsl(158 46% 25%)",
+    "toolErrorBg": "okhsl(19 54% 25%)",
+    "toolTitle": "text",
+    "toolOutput": "muted",
+    "mdHeading": "yellow",
+    "mdLink": "#29c8f2",
+    "mdLinkUrl": "muted",
+    "mdCode": "okhsl(196 65% 78%)",
+    "mdCodeBlock": "green",
+    "mdCodeBlockBorder": "muted",
+    "mdQuote": "muted",
+    "mdQuoteBorder": "muted",
+    "mdHr": "muted",
+    "mdListBullet": "#29c8f2",
+    "toolDiffAdded": "green",
+    "toolDiffRemoved": "red",
+    "toolDiffContext": "muted",
+    "syntaxComment": "okhsl(205 8% 48%)",
+    "syntaxKeyword": "#29c8f2",
+    "syntaxFunction": "yellow",
+    "syntaxVariable": "okhsl(202 58% 67%)",
+    "syntaxString": "okhsl(52 67% 67%)",
+    "syntaxNumber": "green",
+    "syntaxType": "okhsl(196 55% 72%)",
+    "syntaxOperator": "okhsl(205 8% 62%)",
+    "syntaxPunctuation": "muted",
+    "thinkingOff": "okhsl(205 6% 45%)",
+    "thinkingMinimal": "okhsl(196 25% 55%)",
+    "thinkingLow": "okhsl(196 55% 60%)",
+    "thinkingMedium": "#29c8f2",
+    "thinkingHigh": "okhsl(187 70% 66%)",
+    "thinkingXhigh": "okhsl(83 70% 66%)",
+    "thinkingMax": "okhsl(20 85% 66%)",
+    "bashMode": "okhsl(159 64% 65%)"
+  },
+  "export": {
+    "pageBg": "okhsl(205 12% 12%)",
+    "cardBg": "okhsl(205 12% 16%)",
+    "infoBg": "okhsl(196 40% 20%)"
+  }
+}

package/assets/themes/tlc-light.json

@@ -0,0 +1,79 @@
+{
+  "$schema": "https://raw.githubusercontent.com/earendil-works/pi/main/packages/coding-agent/src/modes/interactive/theme/theme-schema.json",
+  "name": "TLC light",
+  "appearance": "light",
+  "vars": {
+    "text": "#313131",
+    "muted": "#555555",
+    "violet": "okhsl(295 60% 46%)",
+    "blue": "okhsl(205 30% 48%)",
+    "green": "okhsl(150 55% 34%)",
+    "red": "okhsl(2 70% 46%)",
+    "yellow": "okhsl(40 80% 36%)",
+    "blueBg": "okhsl(190 55% 90%)",
+    "cyan": "#0dacd6"
+  },
+  "colors": {
+    "accent": "#0dacd6",
+    "border": "okhsl(0 0% 74%)",
+    "borderAccent": "#0dacd6",
+    "borderMuted": "okhsl(0 0% 84%)",
+    "success": "green",
+    "error": "red",
+    "warning": "yellow",
+    "muted": "#555555",
+    "dim": "okhsl(0 0% 55%)",
+    "text": "#313131",
+    "thinkingText": "okhsl(193 40% 42%)",
+    "selectedBg": "okhsl(190 55% 90%)",
+    "scrollbarTrack": "okhsl(0 0% 90%)",
+    "scrollbarThumb": "okhsl(0 0% 72%)",
+    "searchMatchBg": "okhsl(56 22% 91%)",
+    "searchMatchText": "muted",
+    "userMessageBg": "okhsl(190 55% 90%)",
+    "userMessageText": "text",
+    "customMessageBg": "okhsl(190 45% 93%)",
+    "customMessageText": "muted",
+    "customMessageLabel": "#0dacd6",
+    "toolPendingBg": "okhsl(248 3% 91%)",
+    "toolSuccessBg": "okhsl(156 21% 91%)",
+    "toolErrorBg": "okhsl(24 23% 91%)",
+    "toolTitle": "text",
+    "toolOutput": "muted",
+    "mdHeading": "yellow",
+    "mdLink": "#0dacd6",
+    "mdLinkUrl": "muted",
+    "mdCode": "okhsl(193 60% 34%)",
+    "mdCodeBlock": "green",
+    "mdCodeBlockBorder": "muted",
+    "mdQuote": "muted",
+    "mdQuoteBorder": "muted",
+    "mdHr": "muted",
+    "mdListBullet": "#0dacd6",
+    "toolDiffAdded": "green",
+    "toolDiffRemoved": "red",
+    "toolDiffContext": "muted",
+    "syntaxComment": "#6b7280",
+    "syntaxKeyword": "#0dacd6",
+    "syntaxFunction": "yellow",
+    "syntaxVariable": "okhsl(203 73% 46%)",
+    "syntaxString": "okhsl(52 84% 46%)",
+    "syntaxNumber": "green",
+    "syntaxType": "okhsl(193 55% 38%)",
+    "syntaxOperator": "#555555",
+    "syntaxPunctuation": "muted",
+    "thinkingOff": "okhsl(0 0% 62%)",
+    "thinkingMinimal": "okhsl(193 30% 52%)",
+    "thinkingLow": "okhsl(193 55% 44%)",
+    "thinkingMedium": "#0dacd6",
+    "thinkingHigh": "okhsl(178 60% 34%)",
+    "thinkingXhigh": "okhsl(83 65% 38%)",
+    "thinkingMax": "okhsl(20 78% 46%)",
+    "bashMode": "okhsl(159 74% 55%)"
+  },
+  "export": {
+    "pageBg": "okhsl(0 0% 97%)",
+    "cardBg": "okhsl(0 0% 100%)",
+    "infoBg": "okhsl(190 50% 92%)"
+  }
+}

package/bin/learningcode.mjs

@@ -8,12 +8,16 @@ import {
 	MODEL_ID,
 	PI_AGENT_DIR_ENV,
 	PROVIDER_ID,
+	REQUIRED_NODE,
 	TOKEN_ENV,
 	UserError,
 	agentDir,
+	compareVersions,
 	sparkBaseUrl,
 } from "../lib/config.mjs";
+import { GO_PROVIDER, saveProviderKey } from "../lib/auth.mjs";
 import { ensureSparkProvider, modelsPath, retargetProvider } from "../lib/models.mjs";
+import { ensureThemes, preferredTheme } from "../lib/themes.mjs";
 import { hasToken, looksLikeToken, resolveToken, writeCachedToken } from "../lib/token.mjs";
 
 const here = dirname(fileURLToPath(import.meta.url));
@@ -114,6 +118,27 @@ function readModel(toPi) {
 	return undefined;
 }
 
+/**
+ * Fail early and legibly on an unsupported Node.
+ *
+ * `engines` in package.json only makes npm warn, and a warning scrolls past on
+ * a lab machine. The install then succeeds and Pi dies somewhere deep in its own
+ * start-up with a stack trace, which tells a student nothing. Set
+ * LEARNINGCODE_SKIP_NODE_CHECK=1 to bypass if the machine genuinely works.
+ */
+function checkNodeVersion() {
+	if (process.env.LEARNINGCODE_SKIP_NODE_CHECK === "1") return;
+	const running = process.versions.node;
+	if (compareVersions(running, REQUIRED_NODE) >= 0) return;
+
+	throw new UserError(
+		`Node ${REQUIRED_NODE} or newer is required; this is Node ${running}.\n` +
+			"  winget upgrade --id OpenJS.NodeJS.22\n" +
+			"  (or download the LTS build from nodejs.org)\n" +
+			"  Then reinstall: npm i -g @stemtrooper/learningcode",
+	);
+}
+
 function fail(message, code = 1) {
 	process.stderr.write(`learningcode: ${message}\n`);
 	process.exit(code);
@@ -188,6 +213,8 @@ async function main() {
 		return;
 	}
 
+	checkNodeVersion();
+
 	const dir = agentDir();
 	const piEntry = resolvePiEntry();
 	if (!piEntry) {
@@ -202,17 +229,30 @@ async function main() {
 		await retargetProvider(dir, baseUrl);
 	}
 	await ensureSparkProvider(dir);
+	await ensureThemes(dir);
 
 	// `--login` forces a fresh paste even when a token is already cached.
 	const forced = [];
 	const requestedModel = readModel(toPi);
 	const effectiveModel = requestedModel ?? `${PROVIDER_ID}/${MODEL_ID}`;
 	if (!requestedModel) forced.push("--model", effectiveModel);
+
+	// Default to the TLC theme, but never override an explicit choice: --theme on
+	// the command line, or LEARNINGCODE_THEME in the environment.
+	const userPickedTheme = toPi.some(
+		(arg) => arg === "--theme" || arg.startsWith("--theme="),
+	);
+	if (!userPickedTheme && !process.env.LEARNINGCODE_THEME) {
+		forced.push("--theme", preferredTheme());
+	}
+
 	// Spark enforces one active generation per student, so subagents and parallel
 	// tool calls would only earn 429s. Pi is serial by default; skills and rules
 	// are pure prompt-token spend against a 32K ceiling, so they stay off.
 	forced.push("--no-skills");
 	forced.push("--extension", join(here, "..", "extensions", "spark-quota.ts"));
+	forced.push("--extension", join(here, "..", "extensions", "footer.ts"));
+	forced.push("--extension", join(here, "..", "extensions", "banner.ts"));
 	if (process.env.LEARNINGCODE_PI_FLAGS) {
 		forced.push(...process.env.LEARNINGCODE_PI_FLAGS.split(/\s+/).filter(Boolean));
 	}
@@ -278,14 +318,32 @@ async function main() {
 		}
 	}
 
+	const childEnv = { ...process.env };
+
+	// Pi reads provider credentials from auth.json before the environment, and
+	// auth.json is keyed per provider. Storing the key under opencode-go alone
+	// authenticates Go while leaving Zen credential-less, so its 111 pay-per-use
+	// models never register. Zen and Go otherwise share OPENCODE_API_KEY, so
+	// leaving the env var in place would expose both.
+	const goKey = process.env.LEARNINGCODE_GO_KEY || process.env.OPENCODE_API_KEY;
+	if (goKey && process.env.LEARNINGCODE_ALLOW_ZEN !== "1") {
+		await saveProviderKey(dir, GO_PROVIDER, goKey);
+		delete childEnv.OPENCODE_API_KEY;
+		delete childEnv.LEARNINGCODE_GO_KEY;
+	} else if (goKey) {
+		process.stderr.write(
+			"learningcode: LEARNINGCODE_ALLOW_ZEN=1 exposes OpenCode Zen, which bills per token.\n",
+		);
+	}
+
 	const child = spawn(process.execPath, [piEntry, ...forced, ...toPi], {
 		stdio: "inherit",
 		env: {
-			...process.env,
+			...childEnv,
 			[PI_AGENT_DIR_ENV]: dir,
 			SPARK_BASE_URL: sparkBaseUrl(),
 			// Unset rather than empty when not on Spark: Pi treats an empty key as
-			// configured for some providers, which would shadow OPENCODE_API_KEY.
+			// configured for some providers, which would shadow the Go credential.
 			...(token ? { [TOKEN_ENV]: token } : {}),
 		},
 	});

package/extensions/banner.ts

@@ -0,0 +1,123 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { foregroundAnsi, rgbColor } from "@earendil-works/pi-tui";
+
+/**
+ * LEARNINGCODE startup banner.
+ *
+ * Pi lets an extension replace the whole header, which is the supported way to
+ * brand a fork without touching Pi's internals. The built-in header is Pi's own
+ * logo plus key hints; we trade that for the TLC banner and a line of slash
+ * commands, so nothing is claimed about keybindings we cannot read.
+ *
+ * The art is the figlet "ANSI Shadow" face, kept verbatim rather than rebuilt from
+ * a glyph map: the double-line box characters only line up if every row keeps
+ * its exact offset, and a one-space drift makes the whole thing look broken.
+ *
+ * Rendering uses the active theme's colour tokens (`accent`, `border`, `dim`,
+ * `muted`) so the banner stays legible in light and dark terminals instead of
+ * hard-coding colours that break on one of them.
+ */
+
+/**
+ * Only the parts of Pi's Theme this file touches, to keep the runtime import
+ * down to the two colour helpers it actually needs.
+ */
+type ThemeLike = {
+  fg(token: string, text: string): string;
+  /** "light" | "dark" - the background the active theme is designed for. */
+  appearance?: "light" | "dark";
+  /** The terminal's colour capability, e.g. "truecolor". Not light or dark. */
+  getColorMode?(): string;
+};
+type HeaderComponent = { render(width: number): string[] };
+
+/**
+ * TLC brand cyan, sampled from the logo pixels in TLC_BLACKBGND.png and
+ * TLC_WHITEBGND.png rather than eyeballed.
+ *
+ * The banner uses these directly instead of the theme's `accent`, because a
+ * wordmark that changes colour with whatever theme is active stops being a
+ * wordmark. Pi's own logo does the same thing, keeping fixed brand colours and
+ * adapting only for light versus dark terminals.
+ *
+ * Two values because the logo ships two: the darker cyan holds contrast on a
+ * white field, the brighter one on black.
+ *
+ * Note this must not go through `theme.fg()`. That resolves theme *tokens*, and
+ * `Theme.tokenAnsi` throws `Unknown theme color: #29c8f2` for anything that is
+ * not one, so a raw hex there crashes the header at render time. `foregroundAnsi`
+ * takes a colour value directly, and unlike a hand-rolled escape it still
+ * degrades to 256 colour on terminals without truecolour support.
+ */
+const CYAN_DARK_BG = rgbColor(0x29, 0xc8, 0xf2);
+const CYAN_LIGHT_BG = rgbColor(0x0d, 0xac, 0xd6);
+const RESET = "\x1b[0m";
+
+const ART: readonly string[] = [
+  "██╗     ███████╗ █████╗ ██████╗ ███╗   ██╗██╗███╗   ██╗ ██████╗  ██████╗ ██████╗ ██████╗ ███████╗",
+  "██║     ██╔════╝██╔══██╗██╔══██╗████╗  ██║██║████╗  ██║██╔════╝ ██╔════╝██╔═══██╗██╔══██╗██╔════╝",
+  "██║     █████╗  ███████║██████╔╝██╔██╗ ██║██║██╔██╗ ██║██║  ███╗██║     ██║   ██║██║  ██║█████╗",
+  "██║     ██╔══╝  ██╔══██║██╔══██╗██║╚██╗██║██║██║╚██╗██║██║   ██║██║     ██║   ██║██║  ██║██╔══╝",
+  "███████╗███████╗██║  ██║██║  ██║██║ ╚████║██║██║ ╚████║╚██████╔╝╚██████╗╚██████╔╝██████╔╝███████╗",
+  "╚══════╝╚══════╝╚═╝  ╚═╝╚═╝  ╚═╝╚═╝  ╚═══╝╚═╝╚═╝  ╚═══╝ ╚═════╝  ╚═════╝ ╚═════╝ ╚═════╝ ╚══════╝",
+];
+
+const TAGLINE = "The Learning Curve · Sarawak";
+const HINTS = "/help commands · /quota today's spend · /hotkeys keys";
+
+const PAD = "  ";
+
+/** A copy, so a caller mutating the result cannot corrupt later renders. */
+export const bannerArt = (): string[] => [...ART];
+
+export const bannerWidth = (): number => Math.max(...ART.map((line) => line.length));
+
+/**
+ * The art is 97 columns, which does not fit the classic 80 column terminal.
+ * Below the art plus its indent we show a wordmark instead, because clipped box
+ * characters look like a rendering bug rather than a design.
+ */
+const MIN_FULL_WIDTH = bannerWidth() + PAD.length;
+
+export function createBanner(theme: ThemeLike): HeaderComponent {
+	const art = bannerArt();
+	const artWidth = bannerWidth();
+
+	// Two different things, easy to swap by accident:
+	//   appearance    light or dark, decides which brand cyan is readable
+	//   getColorMode  the terminal's colour capability, decides how to emit it
+	// Default to dark so the banner keeps its colour on a host that reports
+	// neither, rather than dropping the brand.
+	const isLight = theme.appearance === "light";
+	const mode = typeof theme.getColorMode === "function" ? theme.getColorMode() : "truecolor";
+	const brand = foregroundAnsi(isLight ? CYAN_LIGHT_BG : CYAN_DARK_BG, mode as never);
+	const ink = (text: string) => `${brand}${text}${RESET}`;
+
+	return {
+		render(width: number): string[] {
+			if (width < MIN_FULL_WIDTH) {
+				return ["", ink(PAD + "learningcode"), theme.fg("muted", PAD + TAGLINE)];
+			}
+
+			const lines = ["", ...art.map((line) => ink(PAD + line))];
+			lines.push(theme.fg("border", PAD + "═".repeat(artWidth)));
+			lines.push(theme.fg("muted", PAD + TAGLINE));
+			lines.push(theme.fg("dim", PAD + HINTS));
+			lines.push("");
+			return lines;
+		},
+	};
+}
+
+/**
+ * `setHeader` lives on ExtensionUIContext, not on the ExtensionAPI the factory
+ * receives, so it has to be reached from an event's context. session_start is the
+ * right moment: extensions are loaded in print and JSON modes too, where there is
+ * no header to replace, and starting work in the factory would run for those.
+ */
+export default function learningcodeBanner(pi: ExtensionAPI) {
+	pi.on("session_start", async (_event, ctx) => {
+		if (!ctx.hasUI || ctx.mode !== "tui") return;
+		ctx.ui.setHeader((_tui, theme) => createBanner(theme as ThemeLike));
+	});
+}

package/extensions/footer.ts

@@ -0,0 +1,128 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+/**
+ * A persistent footer showing what a Spark student actually needs to know:
+ * how much of the day's token budget is gone, and whether their account is
+ * allowed to run at all.
+ *
+ * Spark's quota and seat endpoints are not part of the OpenAI API, so no stock
+ * harness surfaces them. `/v1/me/quota` is the reason this footer exists.
+ *
+ * The value is polled at most every POLL_MS. Agent turns are serial under Spark
+ * (one active generation per student), so a per-turn refresh would add latency
+ * to the thing the student is waiting on for no new information.
+ */
+
+type ThemeLike = { fg(token: string, text: string): string };
+type ComponentLike = { render(width: number): string[] };
+/** Just enough of the TUI to ask for a repaint after the quota changes. */
+type TuiLike = { requestRender?(): void; invalidate?(): void };
+
+const BASE_URL = (process.env.SPARK_BASE_URL || "https://spark.learning.com.my/v1").replace(/\/+$/, "");
+const TOKEN = process.env.SPARK_API_KEY || "";
+
+/** Two minutes. Enough to stay current, rarely enough to be invisible. */
+const POLL_MS = 120_000;
+
+type Quota = { tokensUsed: number; dailyTokenLimit: number; aiEnabled: boolean };
+
+const num = (value: unknown): number =>
+  typeof value === "number" && Number.isFinite(value) ? value : 0;
+
+const pct = (used: number, limit: number): string =>
+  limit > 0 ? `${Math.min(100, Math.round((used / limit) * 100))}%` : "--";
+
+/**
+ * A ten cell meter. Text alone ("82%") is easy to skim past; a bar is read at a
+ * glance, which is the entire reason this is a footer rather than a command.
+ */
+function meter(used: number, limit: number, width = 10): string {
+  if (limit <= 0) return "";
+  const filled = Math.min(width, Math.round((used / limit) * width));
+  return "█".repeat(filled) + "░".repeat(width - filled);
+}
+
+function format(quota: Quota): string[] {
+  if (quota.aiEnabled === false) return ["AI off — ask your teacher"];
+  const { tokensUsed, dailyTokenLimit } = quota;
+  return [
+    `${meter(tokensUsed, dailyTokenLimit)} ${pct(tokensUsed, dailyTokenLimit)}`,
+    `${Math.round(tokensUsed / 1000)}k/${Math.round(dailyTokenLimit / 1000)}k today`,
+  ];
+}
+
+async function fetchQuota(): Promise<Quota | null> {
+  if (!TOKEN) return null;
+  try {
+    const response = await fetch(`${BASE_URL}/me/quota`, {
+      headers: { Authorization: `Bearer ${TOKEN}` },
+    });
+    if (!response.ok) return null;
+    return (await response.json()) as Quota;
+  } catch {
+    return null;
+  }
+}
+
+export default function sparkFooter(pi: ExtensionAPI) {
+  let quota: Quota | null = null;
+  let timer: ReturnType<typeof setInterval> | undefined;
+  let tui: TuiLike | undefined;
+
+  pi.on("session_start", async (_event, ctx) => {
+    if (!ctx.hasUI || ctx.mode !== "tui") return;
+
+    const refresh = async () => {
+      quota = await fetchQuota();
+      // Repaint in place. Notifying would be the wrong tool: an empty
+      // notification still appends a row to the transcript, and the transcript is
+      // what the student is reading.
+      tui?.requestRender?.();
+    };
+
+    ctx.ui.setFooter((footerTui: TuiLike, theme: ThemeLike) => {
+      tui = footerTui;
+      return {
+        render(width: number): string[] {
+          // Nothing to say off Spark, or no token: say so rather than draw a bar
+          // full of empties that reads as "you have spent nothing".
+          if (!TOKEN) {
+            return [theme.fg("dim", "  not on Spark — /login, or use --model opencode-go/…")];
+          }
+          if (!quota) return [theme.fg("dim", "  Spark quota unavailable")];
+
+          if (quota.aiEnabled === false) {
+            return [theme.fg("error", "  AI disabled for your account — ask your teacher")];
+          }
+
+          const { tokensUsed, dailyTokenLimit } = quota;
+          const bar = theme.fg("accent", meter(tokensUsed, dailyTokenLimit));
+          const percent = theme.fg("muted", pct(tokensUsed, dailyTokenLimit));
+
+          // Narrow terminals keep the bar and the percentage only; the absolute
+          // token counts are the part that can be dropped.
+          if (width < 52) return [`  ${bar} ${percent}`];
+
+          const numbers = theme.fg(
+            "dim",
+            `${Math.round(tokensUsed / 1000)}k / ${Math.round(dailyTokenLimit / 1000)}k today`,
+          );
+          return [`  ${bar} ${percent}  ${numbers}`];
+        },
+      };
+    });
+
+    await refresh();
+    timer = setInterval(refresh, POLL_MS);
+    timer.unref?.();
+  });
+
+  pi.on("session_shutdown", async () => {
+    if (timer) clearInterval(timer);
+    timer = undefined;
+    tui = undefined;
+  });
+}
+
+// Exported for tests.
+export const _internals = { format, meter, pct };

package/lib/auth.mjs

@@ -0,0 +1,57 @@
+import { chmod, mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { UserError } from "./config.mjs";
+
+/**
+ * Pi resolves provider credentials from auth.json first, then the environment.
+ * auth.json is keyed by provider id, so a key stored under one provider cannot
+ * satisfy another.
+ *
+ * That matters because OpenCode Zen and OpenCode Go share a single
+ * `OPENCODE_API_KEY` env var. Setting it authenticates *both*, which exposes 111
+ * pay-per-use Zen models alongside the 29 covered by a Go subscription, where
+ * per-turn cost runs to $20/M output on the expensive ones.
+ *
+ * Writing the key under `opencode-go` alone authenticates Go and leaves Zen with
+ * no credential, so Zen models never register. Verified against Pi: with the key
+ * scoped this way, `--list-models claude` reports no matches, while the same
+ * search with the env var set lists Zen's catalogue.
+ */
+export const GO_PROVIDER = "opencode-go";
+
+export function authPath(agentDir) {
+	return join(agentDir, "auth.json");
+}
+
+async function readAuth(agentDir) {
+	try {
+		const parsed = JSON.parse(await readFile(authPath(agentDir), "utf-8"));
+		if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) return parsed;
+		throw new UserError(`${authPath(agentDir)} is not a JSON object. Fix or delete it.`);
+	} catch (error) {
+		if (error instanceof UserError) throw error;
+		if (error?.code !== "ENOENT") {
+			throw new UserError(`Could not parse ${authPath(agentDir)}: ${error.message}`);
+		}
+		return {};
+	}
+}
+
+/**
+ * Store an API key for one provider, preserving any credentials Pi or the user
+ * has already written. Mode 0600 because this file holds bearer tokens.
+ */
+export async function saveProviderKey(agentDir, providerId, key) {
+	const auth = await readAuth(agentDir);
+	auth[providerId] = { type: "api_key", key };
+
+	const path = authPath(agentDir);
+	await mkdir(dirname(path), { recursive: true });
+	await writeFile(path, `${JSON.stringify(auth, null, 2)}\n`, {
+		encoding: "utf-8",
+		mode: 0o600,
+	});
+	// `mode` only applies when creating the file.
+	await chmod(path, 0o600).catch(() => {});
+	return path;
+}

package/lib/config.mjs

@@ -35,6 +35,37 @@ export const TOKEN_ENV = "SPARK_API_KEY";
 /** Where the personal `spark_live_` token is cached between runs. */
 export const TOKEN_FILE = "spark-token";
 
+/**
+ * Pi's floor from its own package.json engines field. npm only warns when a
+ * dependency wants a newer Node, then the install succeeds and the CLI fails
+ * later with something unhelpful, so learningcode checks up front.
+ */
+export const REQUIRED_NODE = "22.19.0";
+
+/**
+ * Compare dotted versions numerically, so "22.9.0" is below "22.19.0".
+ * A leading "v" is stripped because parseInt("v22") is NaN, which would silently
+ * score such a version as 0.
+ */
+export function compareVersions(a, b) {
+	const parse = (value) =>
+		value
+			.trim()
+			.replace(/^v/i, "")
+			.split(".")
+			.map((part) => {
+				const n = Number.parseInt(part, 10);
+				return Number.isFinite(n) ? n : 0;
+			});
+	const left = parse(a);
+	const right = parse(b);
+	for (let i = 0; i < Math.max(left.length, right.length); i += 1) {
+		const diff = (left[i] ?? 0) - (right[i] ?? 0);
+		if (diff !== 0) return diff < 0 ? -1 : 1;
+	}
+	return 0;
+}
+
 /**
  * Pi resolves its agent directory from PI_CODING_AGENT_DIR when set, so
  * learningcode keeps its own config instead of sharing ~/.pi with a stock Pi

package/lib/themes.mjs

@@ -0,0 +1,80 @@
+import { mkdir, readFile, readdir, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { UserError } from "./config.mjs";
+
+/**
+ * TLC brand themes, shipped with the package and seeded into the agent
+ * directory on first run.
+ *
+ * Pi reads themes from `<agentDir>/themes`, which for learningcode is
+ * ~/.learningcode/agent/themes. Seeding rather than forcing keeps the same rule
+ * the provider config follows: an existing file belongs to the student, so it is
+ * never overwritten. Someone who edits tlc-dark.json keeps their edit across
+ * upgrades.
+ */
+
+/** The theme Pi starts with when a terminal reports no colour support. */
+const SYSTEM_THEME = "system";
+
+export const THEME_NAMES = ["tlc-dark", "tlc-light"];
+
+export function themesDir(agentDir) {
+	return join(agentDir, "themes");
+}
+
+function packageThemeDir() {
+	// fileURLToPath, not import.meta.url.pathname: on Windows the pathname is a
+	// /C:/... URL fragment that no path function will resolve.
+	return join(dirname(fileURLToPath(import.meta.url)), "..", "assets", "themes");
+}
+
+/**
+ * Pick which TLC theme suits the terminal. Pi's system theme already probes the
+ * terminal, but it cannot tell us its answer from here, so the choice is made
+ * from the platform default and can be overridden by the caller.
+ */
+export function preferredTheme(env = process.env) {
+	const forced = env.LEARNINGCODE_THEME;
+	if (forced) return forced;
+	// Windows Terminal defaults to a dark scheme for most profiles; macOS and
+	// Linux terminals are more often light. This is a guess either way, which is
+	// why an explicit --theme still wins.
+	return env.LEARNINGCODE_LIGHT_THEME === "1" ? "tlc-light" : "tlc-dark";
+}
+
+/**
+ * Copy any missing theme into the agent directory. Returns the names that were
+ * actually written, so a caller can tell a fresh install from an existing one.
+ */
+export async function ensureThemes(agentDir) {
+	const source = packageThemeDir();
+	const target = themesDir(agentDir);
+	const written = [];
+
+	let available;
+	try {
+		available = await readdir(source);
+	} catch {
+		return written; // themes are a nicety, never a hard failure
+	}
+
+	await mkdir(target, { recursive: true });
+
+	for (const name of THEME_NAMES) {
+		if (!available.includes(`${name}.json`)) continue;
+		const destination = join(target, `${name}.json`);
+		try {
+			await readFile(destination, "utf-8");
+			continue; // already present: the student's copy wins
+		} catch (error) {
+			if (error?.code !== "ENOENT") {
+				throw new UserError(`Could not read ${destination}: ${error.message}`);
+			}
+		}
+		await writeFile(destination, await readFile(join(source, `${name}.json`), "utf-8"), "utf-8");
+		written.push(name);
+	}
+
+	return written;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@stemtrooper/learningcode",
-	"version": "0.1.0",
+	"version": "0.2.1",
 	"description": "TLC Spark coding agent for students: Pi wired to the Spark OpenAI-compatible endpoint with per-student tokens, quota and seat-queue awareness.",
 	"type": "module",
 	"license": "MIT",
@@ -8,6 +8,7 @@
 		"learningcode": "./bin/learningcode.mjs"
 	},
 	"files": [
+		"assets",
 		"bin",
 		"lib",
 		"extensions",
@@ -16,10 +17,12 @@
 	],
 	"scripts": {
 		"start": "node ./bin/learningcode.mjs",
-		"test": "node --test \"test/**/*.test.mjs\""
+		"test": "node --test \"test/**/*.test.mjs\"",
+		"preview": "node ./scripts/preview.mjs"
 	},
 	"dependencies": {
-		"@earendil-works/pi-coding-agent": "1.0.4"
+		"@earendil-works/pi-coding-agent": "1.0.4",
+		"@earendil-works/pi-tui": "1.0.4"
 	},
 	"devDependencies": {
 		"jiti": "2.7.0"
@@ -40,4 +43,4 @@
 		"type": "git",
 		"url": "git+https://github.com/stemtrooper/learningcode.git"
 	}
-}
+}