ava-engine 0.1.0 → 0.3.0

package/lib/platforms.mjs

@@ -2,8 +2,13 @@
 // talker/planner enough to act like a real product specialist for that product:
 // the sign-up → dashboard path, a clean short "journey" for the live progress
 // tracker, and a small knowledge base the agent can retrieve from (RAG).
+//
+// These are built-in samples. Your own products go in playbook files (see
+// lib/playbooks.mjs and docs/setup/customize.md); they're merged in below.
 
-export const PLATFORMS = [
+import { loadPlaybooks, mergePlaybooks, PLAYBOOKS_DIR } from "./playbooks.mjs";
+
+export const BUILTIN_PLATFORMS = [
   {
     id: "todoist", name: "Todoist", url: "https://app.todoist.com",
     category: "Productivity", accent: "#E44332",
@@ -194,6 +199,15 @@ export const PLATFORMS = [
   },
 ];
 
+const custom = loadPlaybooks();
+for (const p of custom.problems) {
+  for (const e of p.errors) console.warn(`  [playbooks] ${p.file} skipped: ${e}`);
+  for (const w of p.warnings) console.warn(`  [playbooks] ${p.file}: ${w}`);
+}
+const hideBuiltins = /^(off|0|false|no)$/i.test(process.env.BUILTIN_PLAYBOOKS || "");
+export const PLATFORMS = mergePlaybooks(BUILTIN_PLATFORMS, custom.playbooks, { hideBuiltins });
+export const CUSTOM_PLAYBOOKS = { count: custom.playbooks.length, dir: PLAYBOOKS_DIR };
+
 export function platformById(id) { return PLATFORMS.find((p) => p.id === id) || null; }
 // Trimmed shape for the onboarding picker in the client (demo-only entries hidden).
 // Demo-only (fictional) products are included, flagged, so demo mode can select

package/lib/playbooks.mjs

@@ -0,0 +1,111 @@
+// Playbooks: the products Ava can onboard people onto, as JSON files you own.
+//
+// Put one file per product in PLAYBOOKS_DIR (default ~/.ava-engine/playbooks), for
+// example acme.json. A file whose id matches a built-in product replaces it.
+// BUILTIN_PLAYBOOKS=off hides the built-in sample products, so the lobby shows only
+// yours. Files are checked when Ava starts: a broken one is skipped with a message
+// saying what to fix, and never stops the server. `ava-engine playbooks` checks
+// them without starting anything.
+
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+const home = (p) => p.replace(/^~(?=$|[\\/])/, homedir()); // .env files don't expand ~
+export const PLAYBOOKS_DIR = home(process.env.PLAYBOOKS_DIR || join(process.env.AVA_HOME || join(homedir(), ".ava-engine"), "playbooks"));
+
+const ID = /^[a-z0-9][a-z0-9-]{0,39}$/;
+const HEX = /^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/;
+const KNOWN = new Set(["id", "name", "url", "category", "accent", "tagline", "firstWin", "path", "optional", "journey", "etaMin", "knowledge", "demoOnly", "$schema"]);
+
+/** Starter file for `ava-engine playbooks new <id>`. */
+export function template(id) {
+  return {
+    id, name: "Acme", url: "https://app.acme.example",
+    category: "Your product", accent: "#4F46E5",
+    tagline: "One line on what the product does and why setup takes a hand.",
+    firstWin: "the moment they get value, e.g. their first report open on the dashboard",
+    path: [
+      "sign in or sign up",
+      "create a workspace (name it, keep the Free plan)",
+      "connect a data source from the Sources page",
+      "open the dashboard and see the first report",
+    ],
+    optional: "Things that can wait until after the first win, e.g. inviting teammates.",
+    journey: ["Sign in", "Create a workspace", "Connect a source", "See your first report"],
+    etaMin: 5,
+    knowledge: [
+      { keywords: "workspace create name plan free", text: "Workspaces hold everything. The Free plan is enough to start and can be upgraded later from Settings → Billing." },
+      { keywords: "source connect csv database import", text: "Sources → Add source connects a database or uploads a CSV. The first sync takes about a minute." },
+    ],
+  };
+}
+
+const str = (v, max) => typeof v === "string" && v.trim().length > 0 && v.length <= max;
+const strList = (v, maxItems, maxLen) => Array.isArray(v) && v.length <= maxItems && v.every((s) => str(s, maxLen));
+
+/**
+ * Check one playbook. Returns { playbook } (normalized, ready to use) or { errors: [...] }.
+ * `fallbackId` is the file name, used when the JSON has no id.
+ */
+export function validatePlaybook(raw, fallbackId) {
+  const errors = [], warnings = [];
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return { errors: ["the file must contain one JSON object"], warnings };
+  const id = raw.id ?? fallbackId;
+  if (!ID.test(String(id ?? ""))) errors.push(`"id" must be lowercase letters, digits and dashes, up to 40 characters (got ${JSON.stringify(id)})`);
+  if (!str(raw.name, 60)) errors.push(`"name" is required (up to 60 characters)`);
+  if (raw.url !== undefined && !(str(raw.url, 300) && /^https?:\/\/[^\s]+$/i.test(raw.url))) errors.push(`"url" must start with http:// or https://`);
+  if (raw.accent !== undefined && !HEX.test(String(raw.accent))) errors.push(`"accent" must be a hex colour like "#4F46E5"`);
+  for (const k of ["category", "tagline", "firstWin", "optional"]) if (raw[k] !== undefined && !str(raw[k], 300)) errors.push(`"${k}" must be text (up to 300 characters)`);
+  if (!strList(raw.journey, 10, 60) || raw.journey.length === 0) errors.push(`"journey" is required: 1 to 10 short step names (up to 60 characters each), shown in the progress tracker`);
+  if (raw.path !== undefined && !strList(raw.path, 12, 400)) errors.push(`"path" must be a list of up to 12 how-to lines (up to 400 characters each)`);
+  if (raw.etaMin !== undefined && !(Number.isInteger(raw.etaMin) && raw.etaMin >= 1 && raw.etaMin <= 120)) errors.push(`"etaMin" must be a whole number of minutes from 1 to 120`);
+  if (raw.demoOnly !== undefined && typeof raw.demoOnly !== "boolean") errors.push(`"demoOnly" must be true or false`);
+  let knowledge = [];
+  if (raw.knowledge !== undefined) {
+    if (!Array.isArray(raw.knowledge) || raw.knowledge.length > 200) errors.push(`"knowledge" must be a list of up to 200 entries`);
+    else raw.knowledge.forEach((e, i) => {
+      const kw = Array.isArray(e?.keywords) ? e.keywords.join(" ") : e?.keywords ?? e?.k;
+      if (!str(e?.text, 1000)) errors.push(`knowledge[${i}]: "text" is required (up to 1000 characters)`);
+      else if (!str(kw, 300)) errors.push(`knowledge[${i}]: "keywords" is required: the words a question would use, e.g. "invoice export csv download"`);
+      else knowledge.push({ k: kw.toLowerCase(), text: e.text });
+    });
+  }
+  for (const k of Object.keys(raw)) if (!KNOWN.has(k)) warnings.push(`unknown field "${k}" is ignored`);
+  if (errors.length) return { errors, warnings };
+  const { name, url, category, accent, tagline, firstWin, optional, etaMin, demoOnly } = raw;
+  return {
+    warnings,
+    playbook: {
+      id, name, url, category: category || "Your product", accent, tagline: tagline || "", firstWin: firstWin || "the first step done",
+      path: raw.path || [], optional, journey: raw.journey, etaMin: etaMin || null, knowledge, ...(demoOnly ? { demoOnly: true } : {}),
+    },
+  };
+}
+
+/** Read every *.json in `dir`. Returns { playbooks, problems: [{file, errors, warnings}] }. */
+export function loadPlaybooks(dir = PLAYBOOKS_DIR) {
+  const playbooks = [], problems = [];
+  if (!existsSync(dir)) return { playbooks, problems, dir };
+  const seen = new Map();
+  for (const file of readdirSync(dir).filter((f) => f.endsWith(".json")).sort()) {
+    let raw;
+    try { raw = JSON.parse(readFileSync(join(dir, file), "utf8")); }
+    catch (e) { problems.push({ file, errors: [`not valid JSON: ${e.message}`], warnings: [] }); continue; }
+    const r = validatePlaybook(raw, file.replace(/\.json$/, ""));
+    if (r.playbook && seen.has(r.playbook.id)) r.errors = [`id "${r.playbook.id}" is already used by ${seen.get(r.playbook.id)}`];
+    if (r.errors?.length) { problems.push({ file, errors: r.errors, warnings: r.warnings }); continue; }
+    if (r.warnings.length) problems.push({ file, errors: [], warnings: r.warnings });
+    seen.set(r.playbook.id, file);
+    playbooks.push({ ...r.playbook, source: file });
+  }
+  return { playbooks, problems, dir };
+}
+
+/** Built-ins plus your files: yours replace a built-in with the same id. */
+export function mergePlaybooks(builtins, custom, { hideBuiltins = false } = {}) {
+  const ids = new Set(custom.map((p) => p.id));
+  // Demo-only built-ins stay: demo mode needs them and the lobby never lists them.
+  const kept = builtins.filter((b) => !ids.has(b.id) && (!hideBuiltins || b.demoOnly));
+  return [...custom, ...kept];
+}

package/lib/spend.mjs

@@ -0,0 +1,59 @@
+// Daily spending cap across every session: DAILY_BUDGET_USD (unset or 0 = no cap).
+//
+// Counts what OpenRouter bills for model calls (its reported usage.cost, or our
+// estimate), per UTC day. Once today's total reaches the cap, new paid calls are
+// refused until midnight UTC. Calls already in flight finish, so the total can
+// overshoot by a few cents. Speech providers (Deepgram, ElevenLabs, Hume) bill
+// separately and aren't counted.
+//
+// The total is saved to SPEND_FILE (default ~/.ava-engine/spend.json) so a restart
+// doesn't reset it. Nothing is written when no cap is set.
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+export const DAILY_BUDGET_USD = Math.max(0, Number(process.env.DAILY_BUDGET_USD) || 0);
+const FILE = process.env.SPEND_FILE || join(process.env.AVA_HOME || join(homedir(), ".ava-engine"), "spend.json");
+
+const today = () => new Date().toISOString().slice(0, 10);
+let ledger = load();
+
+function load() {
+  if (!DAILY_BUDGET_USD) return { day: today(), usd: 0 };
+  try {
+    const j = JSON.parse(readFileSync(FILE, "utf8"));
+    if (typeof j.day === "string" && Number.isFinite(j.usd) && j.usd >= 0) return { day: j.day, usd: j.usd };
+  } catch { /* first run or unreadable: start from zero */ }
+  return { day: today(), usd: 0 };
+}
+
+function current() {
+  const d = today();
+  if (ledger.day !== d) ledger = { day: d, usd: 0 };
+  return ledger;
+}
+
+/** Add the cost of a finished call to today's total. */
+export function recordSpend(usd) {
+  if (!(usd > 0)) return;
+  const l = current();
+  l.usd += usd;
+  if (!DAILY_BUDGET_USD) return;
+  try {
+    if (!existsSync(dirname(FILE))) mkdirSync(dirname(FILE), { recursive: true });
+    writeFileSync(FILE, JSON.stringify(l));
+  } catch (e) { console.warn("  [spend] couldn't save the daily total:", e.message); }
+}
+
+/** True once today's spend has reached DAILY_BUDGET_USD. */
+export function dailyCapReached() {
+  return DAILY_BUDGET_USD > 0 && current().usd >= DAILY_BUDGET_USD;
+}
+
+/** Today's total, for logs and tests. */
+export function spentToday() { return current().usd; }
+
+export class DailyCapError extends Error {
+  constructor() { super("daily spending cap reached"); this.status = 402; this.code = "daily_cap"; }
+}

package/lib/state.mjs

@@ -1,6 +1,7 @@
 // In-memory session store for the flexible agent.
 
 import { randomUUID } from "node:crypto";
+import { emitEvent } from "./webhooks.mjs";
 
 const sessions = new Map();
 const byKey = new Map(); // specialist key → session id (see mintSpecialistKey)
@@ -13,16 +14,24 @@ const MAX_SESSIONS = Number(process.env.MAX_SESSIONS) || 50;
 const MAX_AGE_MS = 6 * 3600 * 1000;
 const IDLE_MS = 30 * 60 * 1000;
 
-function drop(id) {
+function drop(id, reason) {
   const s = sessions.get(id);
-  if (s?.specialistKey) revokeSpecialistKey(s);
+  if (!s) return;
+  if (s.specialistKey) revokeSpecialistKey(s);
   sessions.delete(id);
+  const o = s.ours, wf = o.workflow;
+  emitEvent("session.ended", {
+    sessionId: id, reason, mode: o.mode, platform: o.platform ? { id: o.platform.id, name: o.platform.name } : null,
+    durationSec: Math.round((Date.now() - s.createdAt) / 1000), turns: s.score.ours.turns, costUsd: Math.round(s.score.ours.cost * 1e4) / 1e4,
+    workflow: wf ? { title: wf.title, done: wf.steps.filter((x) => x.status === "done").length, total: wf.steps.length, completed: !!wf.complete } : null,
+    handoffRequested: !!o.handoff?.requested,
+  });
 }
 
 /** Room for one more session? Expired and idle sessions are pruned first. */
 export function hasCapacity() {
   const now = Date.now();
-  for (const [id, s] of sessions) { if (now - s.createdAt > MAX_AGE_MS || now - s.lastActive > IDLE_MS) drop(id); }
+  for (const [id, s] of sessions) { if (now - s.createdAt > MAX_AGE_MS || now - s.lastActive > IDLE_MS) drop(id, "expired"); }
   return sessions.size < MAX_SESSIONS;
 }
 
@@ -39,6 +48,7 @@ export function newSession(opts = {}) {
     lastActive: Date.now(),
     specialistKey: null,         // capability for the human-specialist console; minted on handoff
     ours: {
+      sessionId: id,           // for the events this session's agents report (webhooks)
       mode,                    // "flexible" | "onboarding"
       platform,                // onboarding target {id,name,url,firstWin,path,...} or null
       screenState: null,       // last structured screen state {app,page,elements,state,v}
@@ -108,8 +118,7 @@ export function revokeSpecialistKey(sess) {
 export function endSession(id) {
   const s = sessions.get(id);
   if (!s) return false;
-  revokeSpecialistKey(s);
-  drop(id);
+  drop(id, "hangup");
   return true;
 }
 export function getSessionBySpecialistKey(key) {

package/lib/tts.mjs

@@ -3,6 +3,8 @@
 // audio — works on the oldest device. ElevenLabs/Hume are cloud (paid). "browser"
 // is the on-device Web Speech fallback.
 
+import { loadKokoro, kokoroInstalled } from "./kokoro-model.mjs";
+
 const HAS_ELEVEN = !!process.env.ELEVENLABS_API_KEY;
 const HAS_HUME = !!process.env.HUME_API_KEY;
 const HAS_KOKORO = process.env.KOKORO !== "off"; // local, free — on by default
@@ -13,9 +15,7 @@ const ELEVEN_LABEL = process.env.ELEVEN_LABEL || "Matilda";
 const HUME_VOICE = process.env.HUME_VOICE_ID || "a7ecc00a-6fc0-4546-8126-e12cfd8de3bf";
 const HUME_LABEL = process.env.HUME_LABEL || "Aria";
 const HUME_DESC = process.env.HUME_DESCRIPTION || "Warm, empathetic, natural and reassuring";
-const KOKORO_MODEL = process.env.KOKORO_MODEL || "onnx-community/Kokoro-82M-v1.0-ONNX";
 const KOKORO_VOICE = process.env.KOKORO_VOICE || "af_heart";
-const KOKORO_DTYPE = process.env.KOKORO_DTYPE || "q8";
 
 export const TTS_ENABLED = HAS_KOKORO || HAS_ELEVEN || HAS_HUME;
 const FETCH_TIMEOUT_MS = 20_000;
@@ -50,8 +50,8 @@ let kokoroTTS = null, kokoroInit = null;
 async function initKokoro() {
   if (kokoroTTS) return kokoroTTS;
   if (!kokoroInit) kokoroInit = (async () => {
-    const { KokoroTTS } = await import("kokoro-js");
-    kokoroTTS = await KokoroTTS.from_pretrained(KOKORO_MODEL, { dtype: KOKORO_DTYPE, device: "cpu" });
+    if (!kokoroInstalled()) console.log("  kokoro: downloading the voice model (~90 MB, first run only)…");
+    kokoroTTS = await loadKokoro();
     return kokoroTTS;
   })();
   return kokoroInit;

package/lib/webhooks.mjs

@@ -0,0 +1,68 @@
+// Event webhooks: tell your own systems what happens on calls.
+//
+//   WEBHOOK_URL        one or more URLs (comma-separated) that receive every event as JSON
+//   WEBHOOK_SECRET     signs each delivery: X-Ava-Signature: sha256=HMAC(secret, `${timestamp}.${body}`)
+//   SLACK_WEBHOOK_URL  a Slack incoming webhook; posts when a customer asks for a person
+//   PUBLIC_URL         where specialists open Ava (for the links in those messages)
+//
+// Events: session.started, step.completed, workflow.completed, handoff.requested,
+// session.ended. Delivery is fire-and-forget with one retry, so a slow or broken
+// endpoint never holds up a call.
+
+import { createHmac, randomUUID } from "node:crypto";
+
+const URLS = (process.env.WEBHOOK_URL || "").split(",").map((u) => u.trim()).filter(Boolean);
+const SECRET = process.env.WEBHOOK_SECRET || "";
+const SLACK = process.env.SLACK_WEBHOOK_URL || "";
+const TIMEOUT_MS = 5_000, RETRY_MS = 2_000;
+
+export const WEBHOOKS_ENABLED = URLS.length > 0 || !!SLACK;
+
+/** The URL a specialist opens to join a call. */
+export function specialistUrl(key) {
+  const base = (process.env.PUBLIC_URL || `http://localhost:${Number(process.env.PORT) || 5190}`).replace(/\/+$/, "");
+  return `${base}/specialist?key=${encodeURIComponent(key)}`;
+}
+
+async function post(url, body, headers, label) {
+  for (let attempt = 0; attempt < 2; attempt++) {
+    try {
+      const r = await fetch(url, { method: "POST", headers: { "Content-Type": "application/json", "User-Agent": "ava-engine", ...headers }, body, signal: AbortSignal.timeout(TIMEOUT_MS) });
+      if (r.ok || (r.status >= 400 && r.status < 500 && r.status !== 429)) {
+        if (!r.ok) console.warn(`  [${label}] endpoint refused the event (${r.status})`);
+        return r.ok;
+      }
+    } catch { /* network error or timeout: retry once */ }
+    if (attempt === 0) await new Promise((r) => setTimeout(r, RETRY_MS));
+  }
+  console.warn(`  [${label}] delivery failed after a retry`); // never log the URL: Slack URLs are secrets
+  return false;
+}
+
+/** Signature headers for a delivery body (exported for tests and for receivers to copy). */
+export function sign(body, timestamp, secret = SECRET) {
+  return "sha256=" + createHmac("sha256", secret).update(`${timestamp}.${body}`).digest("hex");
+}
+
+function slackText(type, data) {
+  if (type !== "handoff.requested") return null;
+  const where = data.platform ? ` on ${data.platform.name}` : "";
+  const step = data.workflow?.currentStep ? `\n*Stuck on:* ${data.workflow.currentStep} (${data.workflow.done}/${data.workflow.total} steps done)` : "";
+  const said = data.lastUserMessage ? `\n*Last said:* “${data.lastUserMessage}”` : "";
+  return `:raising_hand: A customer${where} asked to talk to a person.${step}${said}\n<${data.specialistUrl}|Join the call>`;
+}
+
+/** Send an event to every configured endpoint. Returns a promise tests can await; callers needn't. */
+export function emitEvent(type, data) {
+  if (!WEBHOOKS_ENABLED) return Promise.resolve();
+  const event = { id: randomUUID(), type, createdAt: new Date().toISOString(), data };
+  const body = JSON.stringify(event);
+  const jobs = URLS.map((url) => {
+    const ts = String(Math.floor(Date.now() / 1000));
+    const headers = { "X-Ava-Event": type, "X-Ava-Delivery": event.id, "X-Ava-Timestamp": ts, ...(SECRET ? { "X-Ava-Signature": sign(body, ts) } : {}) };
+    return post(url, body, headers, "webhook");
+  });
+  const text = SLACK && slackText(type, data);
+  if (text) jobs.push(post(SLACK, JSON.stringify({ text }), {}, "slack"));
+  return Promise.allSettled(jobs);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ava-engine",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "type": "module",
   "description": "A screen-aware voice agent: sees the tab a user shares, talks them through it, and hands off to a human when needed.",
   "keywords": [
@@ -45,16 +45,20 @@
     "lint": "eslint .",
     "test:all": "npm run lint && npm run check && npm test && npm run test:e2e",
     "demo:record": "node scripts/record-demo.mjs",
-    "cli": "node bin/ava-engine.mjs"
+    "cli": "node bin/ava-engine.mjs",
+    "prepare": "node -e \"if(require('fs').existsSync('.git')&&require('fs').existsSync('.githooks'))try{require('child_process').execFileSync('git',['config','core.hooksPath','.githooks'],{stdio:'ignore'})}catch{}\""
   },
   "dependencies": {
     "@clack/prompts": "1.8.1",
+    "@huggingface/transformers": "3.8.1",
     "kokoro-js": "^1.2.1",
     "sherpa-onnx-node": "^1.13.8",
     "ws": "^8.21.3"
   },
   "devDependencies": {
     "@axe-core/playwright": "^4.13.0",
+    "@commitlint/cli": "21.2.4",
+    "@commitlint/config-conventional": "21.2.4",
     "eslint": "^9.39.5",
     "globals": "^15.15.0",
     "playwright": "1.61"
@@ -70,5 +74,9 @@
   "homepage": "https://github.com/Mr-vero/ava-engine#readme",
   "bugs": {
     "url": "https://github.com/Mr-vero/ava-engine/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
   }
 }

package/public/app.js

@@ -25,6 +25,8 @@ let pip = null;
   try {
     const h = await (await fetch("/api/health")).json();
     S.tts = h.tts || { enabled: false };
+    // Demo mode (no API key): say so up front, in the lobby and on the call.
+    if (h.mock) { $("obDemo").hidden = false; $("demoPill").hidden = false; }
     S.stt = !!(h.stt && h.stt.enabled);
     S.sttStream = !!(h.stt && h.stt.streaming); // offline sherpa streaming ASR on the server
     // speech-recognition engine picker (green room)

package/public/index.html

@@ -47,6 +47,7 @@
       <div class="ob-header">
         <h1>Start a session</h1>
         <p>Choose how Ava should work, then check your audio before connecting.</p>
+        <p class="ob-demo" id="obDemo" hidden><b>Demo mode.</b> Replies are canned until you add an OpenRouter key: run <code>npx ava-engine setup</code>.</p>
       </div>
 
       <div class="ob-section">
@@ -129,6 +130,7 @@
   <span class="vdiv"></span>
   <span class="apptitle" id="apptitle">Flexible Agent</span>
   <span class="mono meta hide-narrow" id="topsub">screen-aware assistant</span>
+  <span id="demoPill" class="pill demo" hidden title="Replies are canned until an OpenRouter key is added">DEMO MODE</span>
   <span id="livepill" class="pill standby"><span class="dot"></span><span id="livepilltext">STANDBY</span></span>
   <div class="grow"></div>
   <span id="privacy" class="privacypill" hidden>

package/public/setup.css

@@ -0,0 +1,97 @@
+@font-face { font-family: "Inter Tight"; src: url(/fonts/inter-tight-var.woff2) format("woff2"); font-weight: 100 900; font-display: swap; }
+@font-face { font-family: "Inter"; src: url(/fonts/inter-var.woff2) format("woff2"); font-weight: 100 900; font-display: swap; }
+@font-face { font-family: "Plex Mono"; src: url(/fonts/plex-mono-400.woff2) format("woff2"); font-weight: 400; font-display: swap; }
+
+:root {
+  --ink: #0A0A0C; --ink2: #4A4B55; --meta: #686975; --line: #E6E6EB; --soft: #F5F5F7; --card: #FFFFFF;
+  --accent: #4F46E5; --accent-tint: rgba(79,70,229,0.08); --ok: #15803D; --ok-tint: #ECFDF3; --err: #B42318; --err-tint: #FEF3F2;
+  --radius: 14px;
+}
+* { box-sizing: border-box; }
+[hidden] { display: none !important; } /* author display rules (e.g. .field) must not un-hide things */
+html, body { margin: 0; background: var(--soft); color: var(--ink); font: 16px/1.5 Inter, -apple-system, "Segoe UI", sans-serif; }
+a { color: var(--accent); }
+code { font: 13px "Plex Mono", ui-monospace, monospace; background: var(--soft); padding: 1px 5px; border-radius: 5px; }
+
+.shell { display: grid; grid-template-columns: 300px 1fr; min-height: 100vh; min-height: 100dvh; }
+.rail { background: var(--ink); color: #fff; padding: 36px 30px; display: flex; flex-direction: column; gap: 36px; }
+.brand { display: flex; align-items: center; gap: 12px; font: 600 20px "Inter Tight", sans-serif; }
+.brand svg { width: 34px; height: 34px; }
+.brand svg rect { fill: #fff; } .brand svg path { stroke: #0A0A0C; }
+.steps { list-style: none; margin: 0; padding: 0; display: flex; flex-direction: column; gap: 6px; counter-reset: s; }
+.steps li { counter-increment: s; display: flex; align-items: center; gap: 12px; padding: 10px 12px; border-radius: 10px; color: #9D9DAB; font-weight: 500; }
+.steps li::before { content: counter(s); width: 26px; height: 26px; flex: none; display: grid; place-items: center; border-radius: 50%; border: 1.5px solid #3A3A46; font: 500 13px "Plex Mono", monospace; }
+.steps li.done { color: #D6D6E0; } .steps li.done::before { content: "✓"; background: #2B2B36; border-color: #2B2B36; }
+.steps li.current { color: #fff; background: #1C1C24; } .steps li.current::before { border-color: #A5A0FF; color: #A5A0FF; }
+.rail-note { margin-top: auto; font-size: 13px; color: #9D9DAB; }
+.rail-note code { background: #1C1C24; color: #D6D6E0; }
+
+.panel { padding: 56px clamp(20px, 6vw, 88px); max-width: 860px; width: 100%; }
+.eyebrow { margin: 0 0 8px; font: 500 13px "Plex Mono", monospace; letter-spacing: .14em; text-transform: uppercase; color: var(--accent); }
+h1 { margin: 0 0 12px; font: 600 clamp(28px, 4vw, 40px)/1.1 "Inter Tight", sans-serif; letter-spacing: -0.025em; }
+.lead { margin: 0 0 28px; color: var(--ink2); font-size: 17px; max-width: 640px; }
+
+.cards { display: grid; gap: 12px; margin-bottom: 24px; }
+.card { position: relative; display: flex; gap: 14px; align-items: flex-start; padding: 18px 20px; background: var(--card); border: 1.5px solid var(--line); border-radius: var(--radius); cursor: pointer; transition: border-color .15s, box-shadow .15s; }
+.card:hover { border-color: #CFCFD8; }
+.card:has(input:checked) { border-color: var(--accent); box-shadow: 0 0 0 4px var(--accent-tint); }
+.card:has(input:focus-visible) { outline: 2px solid var(--accent); outline-offset: 3px; }
+.card input { margin: 4px 0 0; width: 18px; height: 18px; accent-color: var(--accent); flex: none; }
+.card-body { display: flex; flex-direction: column; gap: 3px; flex: 1; }
+.card-body b { font: 600 17px "Inter Tight", sans-serif; }
+.card-body span { color: var(--ink2); font-size: 14.5px; }
+.card:has(.badge) .card-body { padding-right: 84px; }
+.badge { position: absolute; top: 16px; right: 18px; font: 500 12px "Plex Mono", monospace; color: var(--ok); background: var(--ok-tint); padding: 2px 8px; border-radius: 99px; }
+
+.field { display: flex; flex-direction: column; gap: 8px; margin-bottom: 24px; }
+.field label { font-weight: 600; font-size: 15px; }
+.opt { font-weight: 400; color: var(--meta); }
+.row { display: flex; gap: 8px; flex-wrap: wrap; }
+input[type=text], input[type=password], input[type=number] { flex: 1; min-width: 200px; height: 46px; padding: 0 14px; border: 1.5px solid var(--line); border-radius: 10px; font: 15px "Plex Mono", monospace; background: #fff; color: var(--ink); }
+input:focus-visible { outline: none; border-color: var(--accent); box-shadow: 0 0 0 4px var(--accent-tint); }
+input.short { max-width: 160px; flex: none; }
+.hint { margin: 0; color: var(--meta); font-size: 14px; }
+.keep label, .check { font-weight: 400 !important; display: flex; gap: 10px; align-items: center; font-size: 15px; }
+.keep input, .check input { width: 18px; height: 18px; accent-color: var(--accent); }
+
+.connect { display: flex; flex-direction: column; gap: 8px; align-items: flex-start; }
+.or { display: flex; align-items: center; gap: 12px; margin: 10px 0 2px; color: var(--meta); font-size: 14px; }
+.or::before, .or::after { content: ""; flex: 1; height: 1px; background: var(--line); }
+.status { margin: 0; min-height: 22px; font-size: 14.5px; }
+.status.ok { color: var(--ok); } .status.err { color: var(--err); }
+.banner { padding: 14px 18px; border-radius: 12px; margin-bottom: 24px; }
+.banner.error { background: var(--err-tint); color: var(--err); }
+
+.job { background: #fff; border: 1.5px solid var(--line); border-radius: 12px; padding: 14px 16px; margin-bottom: 12px; }
+.job-head { display: flex; justify-content: space-between; font-size: 14.5px; margin-bottom: 10px; font-weight: 500; }
+.job-head span:last-child { font-family: "Plex Mono", monospace; color: var(--meta); }
+.bar { height: 8px; background: var(--soft); border-radius: 99px; overflow: hidden; }
+.bar i { display: block; height: 100%; width: 0; background: var(--accent); border-radius: 99px; transition: width .3s; }
+.job.done .bar i { background: var(--ok); } .job.error .bar i { background: var(--err); }
+
+.summary { display: grid; grid-template-columns: max-content 1fr; gap: 14px 28px; background: #fff; border: 1.5px solid var(--line); border-radius: var(--radius); padding: 22px 24px; margin: 0 0 20px; }
+.summary dt { color: var(--meta); font-size: 14.5px; } .summary dd { margin: 0; font-weight: 500; word-break: break-word; }
+
+.nav { display: flex; justify-content: space-between; align-items: center; margin-top: 32px; gap: 12px; }
+.btn { height: 46px; padding: 0 22px; border-radius: 99px; font: 600 15px "Inter Tight", sans-serif; cursor: pointer; border: 1.5px solid transparent; }
+.btn.primary { background: var(--ink); color: #fff; }
+.btn.primary:hover { background: #24242C; }
+.btn.primary:disabled { background: #B9B9C3; cursor: not-allowed; }
+.btn.ghost { background: #fff; color: var(--ink); border-color: var(--line); }
+.btn.ghost:hover { border-color: #CFCFD8; }
+.btn:focus-visible { outline: 2px solid var(--accent); outline-offset: 3px; }
+
+.launching { text-align: center; padding-top: 12vh; }
+.launching .lead { margin-inline: auto; }
+.orb { width: 120px; height: 120px; margin: 0 auto 36px; border-radius: 50%; background: radial-gradient(circle at 35% 30%, #C9C4FF 0%, #8B7CFF 28%, #5B4FF0 60%, #3B2FC4 100%); box-shadow: 0 0 80px rgba(124,108,246,.55); animation: pulse 1.6s ease-in-out infinite; }
+@keyframes pulse { 50% { transform: scale(1.06); box-shadow: 0 0 120px rgba(124,108,246,.75); } }
+@media (prefers-reduced-motion: reduce) { .orb { animation: none; } .bar i { transition: none; } }
+
+@media (max-width: 760px) {
+  .shell { grid-template-columns: 1fr; }
+  .rail { padding: 20px; gap: 16px; }
+  .steps { flex-direction: row; overflow-x: auto; gap: 4px; }
+  .steps li { padding: 6px 8px; font-size: 0; gap: 0; } .steps li.current { font-size: 14px; gap: 8px; }
+  .rail-note { display: none; }
+  .panel { padding: 32px 16px; }
+}