wizards 0.3.8 → 0.4.1

package/apps/runtime/dist/cli/account.js

@@ -0,0 +1,289 @@
+import * as p from "@clack/prompts";
+import { accountOverview, knownTeam, linkedAccount, unlink, } from "../auth/account.js";
+import { DeviceSignInError, requestDeviceCode, waitForDeviceSignIn } from "../auth/device.js";
+import { migrateControlDb } from "../db/client.js";
+import { env } from "../env.js";
+import { featuresFile, fileFeatures, writeFeature } from "../features.js";
+import { command, readInstallNote, writeInstallNote } from "./home.js";
+import { openBrowser, runningRuntime, settings } from "./start.js";
+import { bold, busy, cyan, dim, tilde } from "./ui.js";
+/**
+ * The account of this install, from the terminal. `wizards account` says where it stands,
+ * `sign-in` runs the device flow (auth/device.ts), `sign-out` ends the link the way the
+ * studio does. The setup's first step is the same sign-in. `--local` keeps an install off the
+ * account altogether: `account=off` in the install's `.features` hides every account surface
+ * (packages/shared/src/feature-flags.ts), and a note in install.json says so.
+ *
+ * Everything here reads and writes the install's settings and vault through the runtime's own
+ * modules, with or without a runtime running (install-env.ts puts this process where the
+ * runtime is). A runtime that runs reads the account from the settings as it goes; what it
+ * holds from its start is brought in line by a restart, which is offered.
+ */
+export const INTRO = "Your team, its space and your wizards live in the account. This computer joins the space.";
+let prepared = null;
+/** The control database as the runtime keeps it: a fresh install has none until something opens it. */
+function ready() {
+    prepared ??= migrateControlDb();
+    return prepared;
+}
+/** Set up with `--local`: the install's `.features` says `account=off`. */
+export function isLocalOnly(file = featuresFile()) {
+    return fileFeatures(file).account === false;
+}
+/** `--local`: the switch into the file, the note into install.json. */
+export function localOnly(paths, file = featuresFile()) {
+    writeFeature("account", false, file);
+    writeInstallNote({ ...readInstallNote(paths), local: true }, paths);
+}
+/** A sign-in ends local-only: the switch follows the default again, the note goes. */
+export function joinedAccount(paths, file = featuresFile()) {
+    if (isLocalOnly(file)) {
+        writeFeature("account", null, file);
+    }
+    const note = readInstallNote(paths);
+    if (note.local) {
+        const { local: _, ...rest } = note;
+        writeInstallNote(rest, paths);
+    }
+}
+/** Where the account stands, from this machine alone: no round trip. */
+export async function accountState() {
+    if (isLocalOnly()) {
+        return { kind: "local" };
+    }
+    await ready();
+    const account = await linkedAccount();
+    if (!account) {
+        return { kind: "none" };
+    }
+    return { kind: "linked", account, team: await knownTeam() };
+}
+/** "Matthias · team Platzer Fenster & Türen · 120 credits", as far as it is known. */
+export function described(account, team, credits = true) {
+    const parts = [account.name || account.email];
+    if (team) {
+        parts.push(`team ${team.name}`);
+        if (credits) {
+            parts.push(`${team.balanceCredits} credits`);
+        }
+    }
+    return parts.join(" · ");
+}
+/** One line for the menu and `wizards status`, after the symbol. */
+export function describeAccount(state) {
+    switch (state.kind) {
+        case "local":
+            return "local only";
+        case "none":
+            return "not signed in";
+        default:
+            return described(state.account, state.team, false);
+    }
+}
+/** The account's site, as people know it: engenty.ai for account.engenty.ai. */
+const host = () => new URL(env.local.accountUrl).host.replace(/^account\./, "");
+/** `wizards account`: where it stands, with the Manage-App's word when it answers. */
+async function status() {
+    const state = await accountState();
+    if (state.kind === "local") {
+        console.log(`Local only (no account). ${dim(`\`${command()} account sign-in\` connects one.`)}`);
+        return 0;
+    }
+    if (state.kind === "none") {
+        console.log(`Not signed in. ${dim(`\`${command()} account sign-in\``)}`);
+        return 0;
+    }
+    const overview = await accountOverview();
+    const team = overview?.tenant ?? state.team;
+    console.log(`Signed in as ${described(state.account, team)} · ${host()}${overview ? "" : dim(`  (${host()} did not answer${team ? "; this is from last time" : ""})`)}`);
+    return 0;
+}
+/**
+ * The device flow on the terminal: the link and the code, the browser opened where there is
+ * one, then a wait while the person allows it. Null when it ended without an account.
+ */
+async function deviceSignIn() {
+    let code;
+    try {
+        code = await requestDeviceCode();
+    }
+    catch (err) {
+        p.log.error(err.message);
+        return null;
+    }
+    const link = code.verificationUriComplete ?? code.verificationUri;
+    p.log.message(`Open ${cyan(link)} and type ${bold(code.userCode)}`);
+    if (openBrowser(link)) {
+        p.log.message(dim("The page opens in your browser."));
+    }
+    const spinner = busy("Waiting for you to allow it in the browser");
+    try {
+        const account = await waitForDeviceSignIn(code);
+        const overview = await accountOverview();
+        spinner.stop(`Signed in as ${described(account, overview?.tenant ?? null)}`);
+        return account;
+    }
+    catch (err) {
+        spinner.fail(err instanceof DeviceSignInError
+            ? err.message
+            : `The sign-in did not work. ${err.message}`);
+        return null;
+    }
+}
+/**
+ * A runtime that runs reads the account from the settings as it goes, but holds a few things
+ * from its start: the Pro modules it loaded, which source the models run on, what was sent to
+ * the cloud. A restart brings it in line; the person is asked, or told how.
+ */
+async function pickUp(paths, interactive, why) {
+    if (!(await runningRuntime(settings(paths).dataDir))) {
+        return;
+    }
+    const how = `${command()} restart`;
+    if (!interactive) {
+        p.log.info(`The studio that runs ${why} after ${cyan(how)}.`);
+        return;
+    }
+    const answer = await p.confirm({
+        message: `Restart the studio that runs, so it ${why}?`,
+        initialValue: true,
+    });
+    if (p.isCancel(answer) || !answer) {
+        p.log.info(dim(`Later: ${how}`));
+        return;
+    }
+    // status.ts shows the account; loaded here when needed, so neither module waits on the other.
+    const { restart } = await import("./status.js");
+    await restart(paths);
+}
+const SIGNED_IN = "fetches the Pro modules of your plan and sends what is published to the cloud";
+async function signIn(paths, interactive) {
+    await ready();
+    const linked = await linkedAccount();
+    if (linked) {
+        p.log.info(`Already signed in as ${described(linked, await knownTeam(), false)}. ${dim(`To switch: \`${command()} account sign-out\` first.`)}`);
+        return 0;
+    }
+    const account = await deviceSignIn();
+    if (!account) {
+        return 1;
+    }
+    joinedAccount(paths);
+    p.log.message(dim("What you publish here runs in the cloud too."));
+    await pickUp(paths, interactive, SIGNED_IN);
+    return 0;
+}
+async function signOut(paths, interactive) {
+    const state = await accountState();
+    if (state.kind !== "linked") {
+        console.log(state.kind === "local" ? "Local only: there is no account to sign out." : "Not signed in.");
+        return 0;
+    }
+    const spinner = busy(`Signing out ${state.account.name || state.account.email}`);
+    await unlink();
+    // The same as the studio's sign-out (DELETE /api/studio/account): what was sent to the cloud
+    // is forgotten, the entitlement goes with the account's plan, and models that ran on its
+    // credits run on own keys again. This process never loaded Pro modules or models, so only the
+    // settings change here; a runtime that runs lets go of its modules on restart.
+    const [{ forgetCloud }, { refreshPro }, models] = await Promise.all([
+        import("../services/cloud.js"),
+        import("../plugins/pro.js"),
+        import("../models.js"),
+    ]);
+    await forgetCloud();
+    await refreshPro();
+    await models.loadLocalModels();
+    if (models.localModelSettings().source === "account") {
+        await models.saveLocalModels({ source: "own" });
+    }
+    spinner.stop("Signed out. Your wizards and results stay on this computer.");
+    await pickUp(paths, interactive, "lets go of the account");
+    return 0;
+}
+/** `wizards account [sign-in|sign-out]`. */
+export async function accountCommand(paths, value, options) {
+    const interactive = !options.yes && Boolean(process.stdin.isTTY && process.stdout.isTTY);
+    switch (value) {
+        case "":
+            return status();
+        case "sign-in":
+        case "signin":
+        case "login":
+            return signIn(paths, interactive);
+        case "sign-out":
+        case "signout":
+        case "logout":
+            return signOut(paths, interactive);
+        default:
+            console.error(`${command()} account [sign-in|sign-out]`);
+            return 2;
+    }
+}
+/** The menu's "Account": where it stands, and the way in or out. */
+export async function accountMenu(paths) {
+    await status();
+    const state = await accountState();
+    const action = await p.select({
+        message: "Account",
+        options: [
+            state.kind === "linked"
+                ? { value: "sign-out", label: "Sign out", hint: "your wizards and results stay here" }
+                : { value: "sign-in", label: "Sign in", hint: "with a code, in your browser" },
+            { value: "back", label: "Back" },
+        ],
+    });
+    if (p.isCancel(action) || action === "back") {
+        return;
+    }
+    if (action === "sign-in") {
+        await signIn(paths, true);
+    }
+    else {
+        await signOut(paths, true);
+    }
+}
+/**
+ * The setup's first step. `--local` keeps the install off the account; else the person is
+ * asked to sign in, unless the setup runs without a terminal (`--yes`), which says how to do
+ * it later.
+ */
+export async function accountStep(paths, options, interactive) {
+    if (options.local) {
+        localOnly(paths);
+        p.log.warn(`Local only. No account, nothing leaves this computer. Wizards, the space and results stay in ${tilde(settings(paths).dataDir)}. Links answer on this computer only.`);
+        p.log.message(dim(`Connect an account any time: ${command()} account`));
+        return;
+    }
+    const state = await accountState();
+    if (state.kind === "local") {
+        p.log.info(`Local only (no account). ${dim(`\`${command()} account sign-in\` connects one.`)}`);
+        return;
+    }
+    if (state.kind === "linked") {
+        const overview = await accountOverview();
+        p.log.success(`Signed in as ${described(state.account, overview?.tenant ?? state.team)}`);
+        return;
+    }
+    p.note(INTRO, "Your engenty account");
+    if (!interactive) {
+        p.log.info(dim(`Sign in later: ${command()} account sign-in`));
+        return;
+    }
+    const answer = await p.confirm({ message: "Sign in now?", initialValue: true });
+    if (p.isCancel(answer)) {
+        p.cancel(`Setup stopped. Run it again with \`${command()} setup\`.`);
+        return "cancelled";
+    }
+    if (!answer) {
+        p.log.info(dim(`Later: ${command()} account`));
+        return;
+    }
+    const account = await deviceSignIn();
+    if (!account) {
+        p.log.info(dim(`Later: ${command()} account sign-in`));
+        return;
+    }
+    joinedAccount(paths);
+    p.log.message(dim("What you publish here runs in the cloud too."));
+    await pickUp(paths, interactive, SIGNED_IN);
+}

package/apps/runtime/dist/cli/install-env.js

@@ -0,0 +1,33 @@
+import { mkdirSync } from "node:fs";
+import { resolve } from "node:path";
+import { layout, readEnvFile } from "./home.js";
+/**
+ * Imported first by the command: before the runtime's modules load, this process sees the
+ * install the way its runtime does. env.ts reads the process once, when it is first imported,
+ * and `.env` from the working directory; the runtime starts in the install's folder (start.ts)
+ * and so reads the install's `.env`, with its data folder beside it. The command goes there
+ * too — else `wizards account` or `wizards status` from another folder would open a `data/`
+ * of its own there, with a secret of its own, and a vault the runtime cannot read.
+ *
+ * What the terminal exports for other projects never reaches the runtime (environment.ts); a
+ * few keys that would make this process another runtime are taken from the install's `.env`
+ * alone. The rest the runtime inherits, so the terminal's word stands.
+ */
+const paths = layout();
+const fileEnv = readEnvFile(paths.envFile);
+/** The install's data folder, as start.ts hands it to the runtime: the terminal's word first. */
+const given = process.env.DATA_DIR?.trim() || fileEnv.DATA_DIR?.trim();
+process.env.DATA_DIR = given ? resolve(paths.home, given) : paths.data;
+for (const key of ["MANAGE_URL", "APP_SECRET", "DATABASE_URL", "DATABASE_AUTH_TOKEN"]) {
+    process.env[key] = fileEnv[key] ?? "";
+}
+// Keys and the account's sign-in live in the Keychain on a Mac, as the runtime keeps them.
+if (process.platform === "darwin" &&
+    process.env.SECRETS === undefined &&
+    fileEnv.SECRETS === undefined) {
+    process.env.SECRETS = "keychain";
+}
+/** Where the command was typed: `wizards validate ./my.wizard` means a path from there. */
+export const startedIn = process.cwd();
+mkdirSync(paths.home, { recursive: true });
+process.chdir(paths.home);

package/apps/runtime/dist/cli/main.js

@@ -1,6 +1,9 @@
+import "./install-env.js";
+import { accountCommand } from "./account.js";
 import { apps, connectCommand } from "./connect.js";
 import { featuresCommand } from "./features.js";
 import { command, layout, packageVersion, readInstallNote } from "./home.js";
+import { startedIn } from "./install-env.js";
 import { CLIENTS, nodeIsCurrent } from "./machine.js";
 import { mcp } from "./mcp.js";
 import { menu } from "./menu.js";
@@ -16,7 +19,9 @@ const HELP = `engenty wizards ${packageVersion()}
                         (needs a terminal)
   ${command()} start      start it and open the studio; it runs in this terminal until Ctrl-C
   ${command()} studio     open the studio; when it does not run, it starts as a service first
-  ${command()} setup      guided setup: an AI client to think with, ffmpeg, start at login
+  ${command()} setup      guided setup: your engenty account, an AI client to think with, ffmpeg,
+                        start at login
+  ${command()} account    your engenty account: status, sign-in, sign-out
   ${command()} open       let this browser into the running studio (--print: only show the link)
   ${command()} status     what is installed and what runs
   ${command()} doctor     status, and what is wrong
@@ -37,6 +42,7 @@ const HELP = `engenty wizards ${packageVersion()}
                         checked on import
 
   --yes, -y          ask nothing and install nothing optional
+  --local            setup without an account: nothing leaves this computer
   --client <name>    install this AI client without asking: ${CLIENTS.map((c) => c.id).join(", ")}
   --no-open          start without opening the browser
   --service, -s      start as a service, detached from this terminal; \`${command()} stop\` stops it
@@ -52,6 +58,7 @@ function parse(argv) {
         paths: [],
         json: false,
         yes: false,
+        local: false,
         open: true,
         service: false,
         print: false,
@@ -62,6 +69,9 @@ function parse(argv) {
         if (arg === "--yes" || arg === "-y") {
             args.yes = true;
         }
+        else if (arg === "--local") {
+            args.local = true;
+        }
         else if (arg === "--no-open") {
             args.open = false;
         }
@@ -90,7 +100,7 @@ function parse(argv) {
         else if (arg.startsWith("-")) {
             return `Unknown option ${arg}.`;
         }
-        else if ((args.command === "autostart" || args.command === "logs") && !args.value) {
+        else if (["autostart", "logs", "account"].includes(args.command) && !args.value) {
             args.value = arg;
         }
         else if (["connect", "disconnect", "features"].includes(args.command)) {
@@ -115,7 +125,7 @@ async function main(argv) {
         return 2;
     }
     const paths = layout();
-    const setupOptions = { yes: args.yes, clients: args.clients };
+    const setupOptions = { yes: args.yes, clients: args.clients, local: args.local };
     if (!args.command) {
         // Without a command: the menu, which needs a terminal. Starting is \`start\`.
         if (args.service || !args.open || args.print) {
@@ -168,6 +178,8 @@ async function main(argv) {
             return update(paths);
         case "autostart":
             return autostart(paths, args.value);
+        case "account":
+            return accountCommand(paths, args.value, { yes: args.yes });
         case "connect":
         case "disconnect":
             return connectCommand(paths, args.apps, args.command === "disconnect");
@@ -176,6 +188,8 @@ async function main(argv) {
         case "features":
             return featuresCommand(args.apps);
         case "validate":
+            // The paths are the person's, from where they typed the command (install-env.ts).
+            process.chdir(startedIn);
             return validateCommand(args.paths, args.json);
         default:
             console.error(`Unknown command ${args.command}.\n\n${HELP}`);

package/apps/runtime/dist/cli/menu.js

@@ -1,5 +1,6 @@
 import * as p from "@clack/prompts";
 import { updateStatus } from "../update.js";
+import { accountMenu, accountState, describeAccount } from "./account.js";
 import { autostartState, setAutostart } from "./autostart.js";
 import { connectCommand } from "./connect.js";
 import { command, packageVersion, readInstallNote } from "./home.js";
@@ -10,14 +11,15 @@ import { badge, cyan, dim, no, ok } from "./ui.js";
 import { update } from "./update.js";
 async function look(paths) {
     const { dataDir } = settings(paths);
-    const [running, atLogin, release] = await Promise.all([
+    const [running, atLogin, release, account] = await Promise.all([
         runningRuntime(dataDir),
         autostartState(paths),
         updateStatus().catch(() => null),
+        accountState(),
     ]);
-    return { running, atLogin, release };
+    return { running, atLogin, release, account };
 }
-function report({ running, atLogin, release }) {
+function report({ running, atLogin, release, account }) {
     const lines = [
         running
             ? `${ok} running  ${cyan(running.url)} ${dim(`pid ${running.pid}, since ${new Date(running.startedAt).toLocaleString()}`)}`
@@ -26,12 +28,15 @@ function report({ running, atLogin, release }) {
     if (!("unavailable" in atLogin)) {
         lines.push(atLogin.on ? `${ok} starts at login` : `${no} does not start at login`);
     }
+    lines.push(account.kind === "linked"
+        ? `${ok} signed in as ${describeAccount(account)}`
+        : `${no} ${describeAccount(account)}`);
     if (release?.newer) {
         lines.push(`${cyan("↑")} ${release.latest} is out ${dim(`(you have ${release.current})`)}`);
     }
     return lines.join("\n");
 }
-function choices({ running, atLogin, release }) {
+function choices({ running, atLogin, release, account }) {
     const options = running
         ? [
             { value: "open", label: "Open the studio", hint: "in your browser" },
@@ -58,7 +63,13 @@ function choices({ running, atLogin, release }) {
             hint: atLogin.on ? "starts at login" : "does not start at login",
         });
     }
-    options.push({ value: "connect", label: "Connect AI apps", hint: "your wizards in Claude, Cursor, Codex …" }, { value: "status", label: "Status", hint: "what is installed, and what is wrong" }, { value: "setup", label: "Setup", hint: "AI client, ffmpeg, start at login" }, { value: "help", label: "Help", hint: "every command" }, { value: "quit", label: "Quit", hint: running ? "it keeps running" : undefined });
+    options.push({ value: "connect", label: "Connect AI apps", hint: "your wizards in Claude, Cursor, Codex …" }, {
+        value: "account",
+        label: "Account",
+        hint: account.kind === "linked"
+            ? `signed in as ${describeAccount(account)}`
+            : describeAccount(account),
+    }, { value: "status", label: "Status", hint: "what is installed, and what is wrong" }, { value: "setup", label: "Setup", hint: "account, AI client, ffmpeg, start at login" }, { value: "help", label: "Help", hint: "every command" }, { value: "quit", label: "Quit", hint: running ? "it keeps running" : undefined });
     return options;
 }
 /** How the service runs: whether it starts at login. Esc goes back to the menu. */
@@ -153,6 +164,9 @@ export async function menu(paths, setupOptions, help) {
             case "connect":
                 await connectCommand(paths, [], false);
                 break;
+            case "account":
+                await accountMenu(paths);
+                break;
             case "status":
                 await status(paths, true);
                 break;

package/apps/runtime/dist/cli/setup.js

@@ -2,6 +2,7 @@ import { appendFileSync, existsSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { delimiter, join } from "node:path";
 import * as p from "@clack/prompts";
+import { accountStep } from "./account.js";
 import { autostartState, setAutostart } from "./autostart.js";
 import { installClient, installCommand } from "./clients.js";
 import { appStates, connectApps } from "./connect.js";
@@ -9,21 +10,9 @@ import { runLogged } from "./exec.js";
 import { command, installedByScript, isCheckout, packageVersion, readInstallNote, writeInstallNote, } from "./home.js";
 import { CLIENTS, detectClients, findChrome, findFfmpeg, findOnPath, suggestedClient, vendorApp, } from "./machine.js";
 import { runningRuntime, settings } from "./start.js";
-import { badge, cyan, dim, tilde } from "./ui.js";
+import { badge, busy, cyan, dim, tilde } from "./ui.js";
 /** The studio as an app of its own: Chrome (or Edge) installs it from the page. */
 const CHROME_APP = "Tip: in Chrome or Edge the studio installs as an app, in a window of its own with its own icon. The studio offers it at the top; or use the install icon in the address bar.";
-/** A spinner on a terminal; where nobody watches, only what came of it. */
-function busy(message) {
-    if (!process.stdout.isTTY) {
-        return { stop: (text) => p.log.step(text), fail: (text) => p.log.warn(text) };
-    }
-    const spinner = p.spinner();
-    spinner.start(message);
-    return {
-        stop: (text) => spinner.stop(text),
-        fail: (text) => spinner.error(text),
-    };
-}
 function cancelled(value) {
     if (p.isCancel(value)) {
         p.cancel(`Setup stopped. Run it again with \`${command()} setup\`.`);
@@ -298,9 +287,10 @@ async function howToUse(paths) {
     ].join("\n"));
 }
 /**
- * The guided setup: what this machine has, what is missing, and what to install — an AI client
- * to think with, ffmpeg, starting at login. It starts nothing; it ends with what runs and how to
- * start, stop and check it. Returns false when it was stopped.
+ * The guided setup: the account this computer joins, then what this machine has, what is
+ * missing, and what to install — an AI client to think with, ffmpeg, starting at login. It
+ * starts nothing; it ends with what runs and how to start, stop and check it. Returns false
+ * when it was stopped.
  */
 export async function setup(paths, options) {
     const interactive = !options.yes && Boolean(process.stdin.isTTY && process.stdout.isTTY);
@@ -310,6 +300,9 @@ export async function setup(paths, options) {
         `Install  ${tilde(paths.home)}${installedByScript() ? "" : dim(`  (data; the code runs from ${isCheckout() ? "this checkout" : "npm"})`)}`,
         `Node     ${process.version}  ${dim(tilde(process.execPath))}`,
     ].join("\n"));
+    if ((await accountStep(paths, options, interactive)) === "cancelled") {
+        return false;
+    }
     if ((await clientsStep(paths, options, interactive)) === "cancelled") {
         return false;
     }

package/apps/runtime/dist/cli/status.js

@@ -1,5 +1,6 @@
 import { accessSync, constants, existsSync, mkdirSync } from "node:fs";
 import { join } from "node:path";
+import { accountState, describeAccount } from "./account.js";
 import { autostartState, setAutostart } from "./autostart.js";
 import { installedByScript, isCheckout, packageRoot, packageVersion } from "./home.js";
 import { detectClients, findChrome, findFfmpeg, nodeIsCurrent } from "./machine.js";
@@ -11,11 +12,12 @@ import { bad, badge, cyan, dim, no, ok, tilde } from "./ui.js";
  */
 export async function status(paths, checks) {
     const { dataDir } = settings(paths);
-    const [running, clients, ffmpeg, atLogin] = await Promise.all([
+    const [running, clients, ffmpeg, atLogin, account] = await Promise.all([
         runningRuntime(dataDir),
         detectClients(paths),
         findFfmpeg(),
         autostartState(paths),
+        accountState(),
     ]);
     const chrome = findChrome();
     const row = (label, value) => console.log(`  ${label.padEnd(9)} ${value}`);
@@ -31,6 +33,7 @@ export async function status(paths, checks) {
     if (!("unavailable" in atLogin)) {
         row("At login", atLogin.on ? `${ok} starts ${dim(`(${atLogin.how})`)}` : `${no} does not start`);
     }
+    row("Account", `${account.kind === "linked" ? ok : no} ${describeAccount(account)}`);
     for (const { client, path, version } of clients) {
         row(client.name.split(" ")[0], path ? `${ok} ${version} ${dim(tilde(path))}` : `${no} not installed`);
     }

package/apps/runtime/dist/cli/ui.js

@@ -1,12 +1,26 @@
 import { homedir } from "node:os";
 import { styleText } from "node:util";
+import * as p from "@clack/prompts";
 const colours = Boolean(process.stdout.isTTY) && !process.env.NO_COLOR;
 /** The name on engenty's orange. */
 export const badge = (text) => colours ? `\x1b[48;2;224;83;27m\x1b[97m\x1b[1m ${text} \x1b[0m` : text;
 export const dim = (text) => styleText("dim", text);
+export const bold = (text) => styleText("bold", text);
 export const cyan = (text) => styleText("cyan", text);
 export const ok = styleText("green", "✓");
 export const no = styleText("yellow", "–");
 export const bad = styleText("red", "✗");
 /** A path as the person would write it. */
 export const tilde = (path) => path.startsWith(homedir()) ? `~${path.slice(homedir().length)}` : path;
+/** A spinner on a terminal; where nobody watches, only what came of it. */
+export function busy(message) {
+    if (!process.stdout.isTTY) {
+        return { stop: (text) => p.log.step(text), fail: (text) => p.log.warn(text) };
+    }
+    const spinner = p.spinner();
+    spinner.start(message);
+    return {
+        stop: (text) => spinner.stop(text),
+        fail: (text) => spinner.error(text),
+    };
+}

package/apps/runtime/dist/docs/dev/plugins/reference.md

@@ -1,7 +1,7 @@
 ---
 title: Reference
 description: Every call, type, address and setting of the plugin framework on one page.
-version: 0.3.4
+version: 0.3.7
 ---
 
 ## Server half
@@ -32,7 +32,8 @@ The default export is a `WizardsPluginFactory`: `(wizards: WizardsPluginApi) =>
 | `registerRunner(runner: PluginRunner)` | [Runners](./runners.md). A door a wizard runs through; `page` runners answer at `/w/<token>/<id>` |
 | `runs` | [Runners](./runners.md#drive-a-run). `start`, `report`, `wizards`, `answerPage`, `review`, `answerAsk`, `control`, `subscribe`, `handoffUrl`, `upload`, `transcribe`: the functions behind the MCP tools, for the plugin's door |
 | `speech.conversation()` | [Runners](./runners.md#a-call). `{ provider: "openai", apiKey, model }`: the tenant's realtime speech model, for a call a plugin drives itself. Throws `503` / `no_model` while none is set up |
-| `registerSpaceContext({ block, tools? })` | [The space](./space.md). `block(space): string \| null` |
+| `registerSpaceContext({ block, tools?, steps? })` | [The space](./space.md). `block(space): string \| null`; `steps`: `agent` (default), `html` (steps that write a document or a dashboard, without the tools) |
+| `spaces.brand(space)` | [The space](./space.md#the-spaces-brand). `{ name, colors, fonts }` of the space, or `null` |
 | `registerAssistantTool(tool: PluginAssistantTool)` | [The space](./space.md#tools-of-the-space-assistant) |
 | `index.put({ space, key, title, text, link? })`, `index.remove(space, key?)` | [The space](./space.md#the-search-index) |
 | `spaceData.putCategories`, `.putPage`, `.putTable`, `.putFile`, `.putDocument`, `.list`, `.readPages`, `.files`, `.readFile`, `.remove`, `.summarize` | [The space](./space.md#knowledge-a-plugin-writes). Knowledge of a space: pages, tables and files under keys of the plugin's own, with their Kategorien; and the space's own pages and files to read |
@@ -45,7 +46,7 @@ The default export is a `WizardsPluginFactory`: `(wizards: WizardsPluginApi) =>
 | `web.fetch(url, init?)`, `web.read(url, { signal? })` | [The web](./server.md#the-web) |
 | `documents.parse({ data, name, mime }, { signal? })` | [Documents](./server.md#documents). `{ markdown, pages }` |
 | `getTenantDb(): PluginDb` | The current tenant's database, a Drizzle libSQL database |
-| `generate(request): Promise<{ text, object }>` | Asks a model of the current tenant: `prompt`, `system?`, `schema?`, `model?`, `maxOutputTokens?`, `signal?`. See [The server half](./server.md#asking-a-model) |
+| `generate(request): Promise<{ text, object }>` | Asks a model of the current tenant: `prompt`, `system?`, `schema?`, `model?`, `maxOutputTokens?`, `signal?`, `files?` (pictures and PDFs: `{ data, mediaType, name? }[]`). See [The server half](./server.md#asking-a-model) |
 | `connections.available(ids)`, `.start({ space, connector, actions })`, `.connect({ space, connector, actions, credentials })`, `.list(space)`, `.get(id)`, `.call(id, action, input)`, `.remove(id)` | [Accounts](./connections.md) |
 | `secrets.seal(value): string`, `secrets.unseal(sealed)` | [Keys of the plugin's own](./server.md#keys-of-the-plugins-own). `unseal` gives null for a value sealed on another install |
 | `registerAssistantContext({ block })` | [The space](./space.md#the-assistant-on-the-plugins-own-page). `block(space): string \| null` |
@@ -240,11 +241,13 @@ The default export is a `StudioPlugin`: `(studio: StudioPluginContext) => void`.
 | `studio.registerShareSection({ runner, component })` | [Runners](./runners.md#the-runners-part-of-the-share-dialog). The runner's own settings for a wizard (a keyword), under the share dialog's gear once it is switched on and set up. `component` gets `{ wizard: { id, title } }` |
 | `studio.registerAssistantCard({ tool, component })` | Draws a tool's result in the space assistant's chat. `component` gets `{ data, send }` |
 | `studio.registerSpaceSection({ id, group?, label, hint?, component })` | A section of a part of the space page at `/studio/space/<group>#<id>`; `group`: `info`, `knowledge` (default), `data` or `results` |
+| `studio.registerSpacePart({ id, label, icon, after?, component })` | [A part of the plugin's own](./studio.md#a-part-of-the-plugins-own) at `/studio/space/<id>`, after `info`, `knowledge` or `data` (default) in the menu |
+| `studio.useSpaceMenu(entries)` | A hook in a plugin's part: its menu, `{ id, label, icon? }[]`, each jumping to the element with that id |
 | `studio.useCrumbs(items)` | A hook: the trail in the top bar for the page shown, `{ label, to? }[]`, instead of a heading of the page's own |
 | `studio.Assistant` | Tells the studio's assistant what to say on a page of the plugin: `title?`, `hello?`, `placeholder?`, `suggestions?: { label, message?, fill? }[]`, `onChanged?`. Draws nothing |
 | `studio.useAssistantPage(page)` | A hook: what the page shows, for the assistant: `open?: { kind, id?, label }`, `selection?`, `summary?`, `fields?: { id, label, value }[]`, `compact?`, and the words of `studio.Assistant` |
 | `studio.useAssistantTool(name, { description, parameters? }, run)` | A hook: a tool the assistant runs in the page while it is shown, as `<plugin>_<name>`. `parameters`: JSON Schema; `run(args)` returns what the assistant learns |
-| `studio.useSpace()` | A hook: `{ id, name, readOnly }` of the space the studio shows, or `null` |
+| `studio.useSpace()` | A hook: `{ id, name, readOnly, brand }` of the space the studio shows, or `null`; `brand` is `{ name, colors, fonts }` |
 | `studio.i18n.register({ de, en })` | Gives `t(key, vars?)` |
 | `studio.i18n.lang()` | `"de"` or `"en"` |
 | `studio.api.get`, `.post`, `.put`, `.patch`, `.del` | The plugin's own routes |

package/apps/runtime/dist/docs/dev/plugins/server.md

@@ -1,7 +1,7 @@
 ---
 title: The server half
 description: The function a plugin exports, what it is handed, and the rules it runs under.
-version: 0.3.2
+version: 0.3.7
 ---
 
 The server half is a file whose default export is a function. The runtime calls it once when the
@@ -39,6 +39,7 @@ export default definePlugin((wizards) => {
 | `registerAssistantTool(tool)` | A tool of the space assistant | [The space](./space.md#tools-of-the-space-assistant) |
 | `registerAssistantContext(context)` | What the space assistant is told on the plugin's own page | [The space](./space.md#the-assistant-on-the-plugins-own-page) |
 | `spaceData.putPage(input)`, `putTable`, `putFile`, `putDocument`, `putCategories`, … | Knowledge of a space: pages, tables, files and Kategorien | [The space](./space.md#knowledge-a-plugin-writes) |
+| `spaces.brand(space)` | The space's look: its title, colours and fonts | [The space](./space.md#the-spaces-brand) |
 | `index.put(entry)`, `index.remove(space, key?)` | Texts in the space's search index | [The space](./space.md#the-search-index) |
 | `registerHttpRoute(route)` | A route below `/api/studio/plugins/<id>` | [Routes](./routes.md) |
 | `registerPublicRoute(route)`, `publicUrl(path)` | A route anyone may call, and its address | [Routes](./routes.md#public-routes) |
@@ -106,6 +107,7 @@ const { object } = await server.generate({
 | `model` | `classifier` (fast, cheap), `standard`, `high`, `highest` | `standard` |
 | `maxOutputTokens` | A limit on the answer | the model's |
 | `signal` | Aborts the call | two minutes |
+| `files` | Pictures (PNG, JPEG, WebP, GIF) and PDFs the model looks at with the prompt: `{ data, mediaType, name? }[]`, `data` a `Uint8Array` | none |
 
 It answers `{ text, object }`. Without a model set up it throws an error with the status `503`
 and the code `no_model`: a route that lets it through answers just that, and the studio half