@engenty/wizards-runtime 0.7.7 → 0.7.9

package/apps/runtime/dist/db/migrations/tenant/meta/_journal.json

@@ -120,6 +120,13 @@
       "when": 1792044239427,
       "tag": "0016_even_trish_tilby",
       "breakpoints": true
+    },
+    {
+      "idx": 17,
+      "version": "6",
+      "when": 1792271496354,
+      "tag": "0017_run_client",
+      "breakpoints": true
     }
   ]
 }

package/apps/runtime/dist/db/schema.js

@@ -127,6 +127,8 @@ export const run = sqliteTable("run", {
      * (`data-page` of the embed tag, else the page's own address); null on the wizard's link.
      */
     origin: text("origin"),
+    /** The client that started it over the public API (`x-wizards-client`): web, app, cli, or a registered id. */
+    client: text("client"),
     status: text("status", {
         enum: ["waiting_input", "running", "done", "failed", "cancelled"],
     }).notNull(),

package/apps/runtime/dist/decision-model.js

@@ -0,0 +1,33 @@
+/**
+ * A decision model on the person's own machine: Cloudflare's Clef-flash (open weights, Apache
+ * 2.0), which Ollama 0.35 and newer serves at /v1/systemone with the same questions and answers
+ * as TypeSafe's Jev. The setup offers to pull it; the runtime asks it where no hosted decision
+ * model is set up.
+ */
+/** The model the setup pulls. Clef, its larger sibling, is taken as well where it is there. */
+export const LOCAL_DECISION_MODEL = "clef-flash";
+/** Ollama's own address from the one the runtime uses for its OpenAI-style API (…/v1). */
+export function ollamaRoot(url) {
+    return url.trim().replace(/\/+$/, "").replace(/\/v1$/, "");
+}
+/** The decision model among the models Ollama lists: Clef-flash, else Clef. */
+export function decisionModelIn(names) {
+    const named = (base) => names.find((n) => n === base || n.startsWith(`${base}:`));
+    return named(LOCAL_DECISION_MODEL) ?? named("clef") ?? null;
+}
+/** The decision model the Ollama at `url` holds; null where it does not run or has none. */
+export async function ollamaDecisionModel(url, timeoutMs = 1500) {
+    try {
+        const res = await fetch(`${ollamaRoot(url)}/api/tags`, {
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+        if (!res.ok) {
+            return null;
+        }
+        const { models } = (await res.json());
+        return decisionModelIn((models ?? []).map((m) => m.name));
+    }
+    catch {
+        return null;
+    }
+}

package/apps/runtime/dist/docs/dev/api.md

@@ -0,0 +1,39 @@
+---
+title: The API
+description: What a program may rely on when it talks to a runtime, and what is private.
+version: 0.7.7
+---
+
+A runtime answers HTTP under `/api`. Three parts are a contract: they are versioned, documented
+and change with notice. Everything else is the studio’s own and changes without notice.
+
+## What a program may rely on
+
+| Part | For | Signed in as |
+|---|---|---|
+| `/api/v1/…` | programs that build and publish wizards: the spaces of a local install, importing a wizard | an access token of the account, with scopes (`wizards:read`, `wizards:write`, `wizards:publish`, `runs:test`); see [the Manage-App contract](https://github.com/engenty/engenty-wizards/blob/main/docs/manage-contract.md) |
+| `/api/mcp` | AI apps: every tool of [the MCP server](../user/ai-apps.md) | the same tokens, or the local ticket `wizards mcp` carries |
+| The public run API: `/api/public/wizards/:token`, `/api/public/wizards/:token/runs`, `/api/public/codes/:code`, `/api/runs/:id/…` | running a published wizard by its link: what the runner in a browser does | nobody; a visitor cookie, or the `x-wizards-visitor` header where a cookie does not survive |
+
+## Private
+
+`/api/studio/…`, `/api/auth/…` and `/api/internal/…` belong to the studio, the sign-in and the
+Manage-App. They change with every release and are not meant for other programs. A program that
+needs something only they have asks for it on `/api/v1`.
+
+## Who you are: `x-wizards-client`
+
+Every start of a run over the public API names the client that starts it, in the
+`x-wizards-client` header: `web` is the runner in a browser, `app` the mobile app, `cli` the
+command line. A client of your own sends its own id: lower-case letters, digits and hyphens.
+The run keeps the id.
+
+The id is no secret and proves nothing. It carries the terms a client runs under:
+
+| Runtime | Does with the id |
+|---|---|
+| One that runs alone (your computer, your server) | Keeps it on the run. Nothing is refused: the API is yours |
+| engenty.ai | Asks its list of clients: a registered id runs under its limits, an unknown one under the public limits, a revoked one not at all. The [terms of the hosted API](https://engenty.ai/api-terms) say how a client registers and what it may do |
+
+An answer of `403` with `code: "client_refused"` means the id may not start runs there;
+`429` with `code: "client_limit"` means it started too many this hour.

package/apps/runtime/dist/docs/dev/index.md

@@ -15,6 +15,7 @@ code, and the runtime loads it from its files while it runs.
 | [Quick start](./plugins/quick-start.md) | A tool for AI steps in one file that works in two minutes |
 | [Reference](./plugins/reference.md) | Every call, type, address and setting |
 | [Examples](./plugins/examples.md) | Two plugins to read and copy |
+| [The API](./api.md) | What a program may rely on, what is private, and how a client names itself |
 
 ## Wizards as files
 

package/apps/runtime/dist/docs/dev/integration/openui.md

@@ -11,9 +11,11 @@ author defined. `@engenty/wizards/openui` puts the two together: the chat decide
 fits and what it already knows, the wizard then runs inside the conversation, and the chat
 hears the result.
 
-It is part of `@engenty/wizards`, the package for code outside engenty wizards
-([`packages/wizards/src/openui`](https://github.com/engenty/wizards/tree/main/packages/wizards/src/openui)
-in the repository, under the MIT licence). A whole chat to try it with is `examples/openui-chat`.
+It is part of `@engenty/wizards`, the package on npm for code outside engenty wizards
+(`npm install @engenty/wizards`;
+[`packages/wizards/src/openui`](https://github.com/engenty/wizards/tree/main/packages/wizards/src/openui)
+in the repository, under FSL-1.1-MIT; the runner it bundles is MIT). A whole chat to try it with
+is `examples/openui-chat`.
 
 ## What OpenUI is
 

package/apps/runtime/dist/docs/dev/meta.json

@@ -3,5 +3,5 @@
   "description": "Extend engenty wizards with plugins: tools for AI steps, routes with their own tables, pages in the studio.",
   "root": true,
   "icon": "SquareTerminal",
-  "pages": ["index", "wizard-format", "plugins", "integration"]
+  "pages": ["index", "wizard-format", "plugins", "integration", "api"]
 }

package/apps/runtime/dist/docs/user/ai-apps.md

@@ -103,10 +103,21 @@ a minute, even with a token it already holds.
 
 ## The Claude Code plugin
 
-If engenty wizards has a public https address, Claude Code can also install a plugin. It adds
-the `/wizard` command and the skills to build and use wizards:
+Claude Code can also install a plugin. It adds the `/wizard` command, the skills to build and
+use wizards, and `/wizards`, a pane beside the chat that lists your wizards and opens one in the
+app’s browser pane. From GitHub, for the `engenty-wizards` server your AI apps already have:
+
+```bash
+claude plugin marketplace add engenty/wizards
+claude plugin install wizards@engenty
+```
+
+If engenty wizards has a public https address, it serves the plugin with its server bundled:
 
 ```bash
 claude plugin marketplace add <your address>/api/claude-plugin/marketplace.json
-claude plugin install engenty-wizards@engenty
+claude plugin install wizards@<your-host-with-dashes>   # wizards.example.com → wizards-example-com
 ```
+
+`claude plugin update wizards` brings the next version. In Claude Code’s auto mode the pane’s own
+calls need allow rules; the plugin’s README names them.

package/apps/runtime/dist/docs/user/command-line.md

@@ -11,7 +11,7 @@ version: 0.5.0
 | `wizards` | Shows what is running, and a menu. While it runs, you can open the studio, restart or stop it; while it doesn’t, “Start in the background” or “Start in this terminal”. Then “Update”, which restarts it into the new version, “Start at login”, “Connect AI apps”, “Account”, “Status”, “Setup”, “Uninstall” and “Help”. The first time, the setup runs first. It needs a terminal |
 | `wizards start` | Starts it and opens the studio. It runs in that terminal, and Ctrl-C stops it. The first time, the setup runs first |
 | `wizards studio` | Opens the studio in your browser. If it isn’t running, it starts in the background first |
-| `wizards setup` | Runs the guided setup again: your account, an AI client, the browser and ffmpeg, start at login, your AI apps. `--local` leaves the account out ([Local only](./local-only.md)) |
+| `wizards setup` | Runs the guided setup again: your account, an AI client, the browser and ffmpeg, a decision model, start at login, your AI apps. `--local` leaves the account out ([Local only](./local-only.md)) |
 | `wizards account` | Shows the account this computer is signed in to: who, which team, the credits. `sign-in` shows a link and a code and opens your browser; `sign-out` disconnects this computer |
 | `wizards open` | Signs this browser in to the running studio. `--print` only prints the link; it works once, within a minute |
 | `wizards status` | Shows what is installed and running, with the browser it uses for PDF, PNG and websites |

package/apps/runtime/dist/docs/user/install.md

@@ -32,6 +32,7 @@ have is left alone), installs engenty wizards into `~/.engenty/wizards` (about 6
 | Your engenty account | Asks “Sign in or create your account now?”. If you say yes, it shows a link and a code and opens your browser for the sign-in at account.engenty.ai; check that the page shows the same code (if you have no account yet, the page creates one with your invitation code, or puts you on the waitlist). While it waits, Enter opens the page again and Esc goes on without an account. Once you are signed in, what you publish on this computer runs in the cloud too. If you say no, `wizards account sign-in` does it any time. Setting it up again with `--local` signs an account out. `--local` leaves the account out altogether: see [Local only](./local-only.md) |
 | An AI client | Looks for Codex, Claude Code, Antigravity and Cursor Agent and offers to install the ones that are missing. It puts first the one whose app (ChatGPT, Claude, Antigravity, Cursor) is on your Mac, as you most likely have that subscription already. You can also use your account’s credits, an API key, [Ollama](https://ollama.com) or, on a Mac with Apple silicon and macOS 26, Apple Intelligence: the studio’s [first page](./first-start.md) offers them |
 | A browser and ffmpeg | Names the browser for PDF and PNG exports and steps on websites: the first of Chrome, Edge and Chromium it finds (on a Mac also Brave). engenty wizards uses that one; [`CHROME_PATH`](./command-line.md#settings) picks another. It also says whether ffmpeg is there for MP4 videos of animated widgets, and with Homebrew it offers to install it |
+| A decision model (optional) | Offers to install [Ollama](https://ollama.com) if it isn’t there and to download Cloudflare’s Clef-flash into it (about 11 GB). The wizards then make their decisions, such as which branch to take, on your computer, without a key or credits. On a Mac the Ollama app goes into Applications and, when it first starts, asks once for your Mac’s password to set up its `ollama` command (cancel works too); on Linux Ollama’s own installer runs, installs `zstd` if it is missing, and asks for your password |
 | Start at login (optional) | engenty wizards starts in the background when you log in, so links and AI apps can always reach it. It is a LaunchAgent on a Mac and a systemd user service on Linux |
 | Your AI apps (optional) | Offers to add your wizards to the [AI apps](./ai-apps.md) it finds, such as Claude Desktop, Cursor or Codex |
 | The command | If `~/.local/bin` is not on your PATH, it offers to add it in your shell’s settings file |

package/apps/runtime/dist/engine/decide.js

@@ -32,7 +32,9 @@ async function askSystemOne(input, signal) {
                 return readSystemOne(input.questions, await res.json());
             }
             if (!(RETRYABLE.has(res.status) && attempt < 2)) {
-                console.warn(`[decide] the decision model answered ${res.status}`);
+                const why = (await res.text().catch(() => "")).trim().slice(0, 300);
+                access.refused?.(res.status, why);
+                console.warn(`[decide] the decision model answered ${res.status}${why ? `: ${why}` : ""}`);
                 return {};
             }
         }

package/apps/runtime/dist/engine/runner.js

@@ -174,6 +174,7 @@ export async function createRun(input) {
         origin: input.origin ?? null,
         lang: input.lang ?? null,
         unattended: input.unattended ?? false,
+        client: input.client ?? null,
         status: first.type === "page" ? "waiting_input" : "running",
         cursor: first.id,
         state,

package/apps/runtime/dist/film/project.js

@@ -1,6 +1,6 @@
 import { createHash } from "node:crypto";
 import { existsSync } from "node:fs";
-import { cp, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { cp, mkdir, readdir, readFile, rm, writeFile } from "node:fs/promises";
 import { dirname, join, normalize } from "node:path";
 import { dataRef, FILM_SIZES } from "@engenty-wizards/shared/definition";
 import { gradientCss, ruleLines, textStyleLine } from "@engenty-wizards/shared/projects";
@@ -52,21 +52,43 @@ async function put(root, rel, data) {
     await writeFile(path, data);
 }
 const safeName = (name) => name.replace(/[^A-Za-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "") || "file";
-function rules(step, skills) {
+/** Where the client starts, by how film/ began. */
+function startRules(start) {
+    if (start === "base") {
+        return `- **What to make:** BRIEF.md. **Start here:** film/ is already the wizard's base project in this
+  format — read film/PARTS.md first: its scene templates carry the look. Compose the film from them in
+  the one file PARTS.md names, timed to the voice; write a new scene only where no template fits, then
+  in the style of showcase/ (SHOWCASE.md says how each technique is made).
+- **The brand:** film/brand/ holds brand.json and the logos. If film/brand/theme.json is missing, make
+  it first as film/BRAND.md says — it is kept for the next films of this space, so get it right.
+  Colours, logo and fonts come from there only.
+`;
+    }
+    if (start === "from") {
+        return `- **What to make:** BRIEF.md. **Start here:** film/ holds a finished film of this run in another
+  format. Lay it out for this one: scenes, timing, words and sound stay; only the layout changes
+  (film/PARTS.md says how when it exists). The look is showcase/'s.
+- **The brand:** film/brand/ when it is there, else brand/brand.json and brand/logos/ — colours, logo
+  and fonts come from there only.
+`;
+    }
+    return `- **What to make:** BRIEF.md. **The bar:** showcase/ (read showcase/SHOWCASE.md and showcase/frame.md
+  first when it exists, look at its stills, reuse its helpers from showcase/assets/). **The brand:**
+  brand/brand.json and brand/logos/ — colours, logo and fonts come from there only.
+`;
+}
+function rules(step, skills, start) {
     const size = FILM_SIZES[step.format];
     return `# The film folder
 
 You make one film here, autonomously, to the end. Nobody answers questions: where a skill asks the
 person, decide yourself and note it in PROGRESS.md.
 
-- **What to make:** BRIEF.md. **The bar:** showcase/ (read showcase/SHOWCASE.md and showcase/frame.md
-  first when it exists, look at its stills, reuse its helpers from showcase/assets/). **The brand:**
-  brand/brand.json and brand/logos/ — colours, logo and fonts come from there only.
-- **Material:** input/ (see input/README.md). Use nothing from the web; you have no network.
+${startRules(start)}- **Material:** input/ (see input/README.md). Use nothing from the web; you have no network.
 - **Skills:** ${skills.join(", ")} in .claude/skills/<name>/SKILL.md. Start with \`hyperframes\` and
   read the skill files directly; do not update or install skills.
-- **The HyperFrames project is film/** (${size.width}×${size.height}, already set up). Keep every file
-  of the film inside film/.
+- **The HyperFrames project is film/** (${size.width}×${size.height}). Keep every file of the film
+  inside film/.
 - **Running HyperFrames:** only through the \`hyperframes\` tool (MCP server \`film\`), e.g.
   \`["lint","film"]\`, \`["check","film"]\`, \`["snapshot","film","--at","1,4,8"]\`,
   \`["render","film","-q","draft"]\`, \`["transcribe","input/voice/l01.wav","--json","-d","input/voice"]\`.
@@ -86,57 +108,25 @@ person, decide yourself and note it in PROGRESS.md.
 - Install nothing (no pip, brew, npm).
 `;
 }
-/** Sets up the folder for a first attempt; a later attempt finds it as it was left. */
-export async function prepareFilmFolder(step, ctx) {
-    const root = filmRoot(ctx.runId, step.id);
-    const brief = renderTemplate(step.brief, ctx.scope).trim();
-    // The same brief and material as last time: the film is there to go on with or to change.
-    const stamp = createHash("sha256")
-        .update(JSON.stringify([
-        brief,
-        Object.values(step.inputs).map((raw) => {
-            const ref = dataRef(raw);
-            const [head, id] = ref.split(".");
-            return head === "steps" ? ctx.state.outputs[id]?.at : ctx.state.values[ref];
-        }),
-    ]))
-        .digest("hex");
-    const stampFile = join(root, ".engenty", "inputs");
-    const same = existsSync(stampFile) && (await readFile(stampFile, "utf8")) === stamp;
-    if (same && existsSync(join(root, "film", "index.html")) && (await savedSession(root))) {
-        return { root, brief };
-    }
-    await rm(root, { recursive: true, force: true });
-    await mkdir(root, { recursive: true });
-    const skills = await placeSkills(step.skills, ctx.files, join(root, ".claude", "skills"));
-    const size = FILM_SIZES[step.format];
-    await put(root, "BRIEF.md", `# Brief\n\nFormat ${step.format}, ${size.width}×${size.height}${step.seconds ? `, about ${step.seconds} s` : ""}. Language of all text on screen: the brief's language.\n\n${brief}\n`);
-    const text = rules(step, skills);
-    await put(root, "CLAUDE.md", text);
-    await put(root, "AGENTS.md", text);
-    // The style kit.
-    if (step.kit) {
-        const file = ctx.files.find((f) => f.path === step.kit);
-        if (file) {
-            const entries = unzipSync(new Uint8Array(await getBlob(file.hash)));
-            for (const [name, data] of Object.entries(entries)) {
-                if (!name.endsWith("/")) {
-                    await put(join(root, "showcase"), name.replace(/^showcase\//, ""), data);
-                }
-            }
-        }
-    }
-    // The space's brand.
+const BRAND_STAMP = join(".engenty", "brand");
+/**
+ * Writes the space's brand into brand/ as it is now (brand.json, logos). True when it differs
+ * from what the folder had before — the film's code then still carries the old one.
+ */
+async function writeBrand(root, ctx) {
     const b = ctx.scope.brand;
-    const logos = [];
+    const hash = createHash("sha256");
+    const files = [];
+    const fileName = (dir, f) => `${dir}/${safeName(f.name.replace(/\.[^.]+$/, ""))}.${extFor(f.mime) === "bin" ? (f.name.split(".").pop() ?? "bin") : extFor(f.mime)}`;
     const patterns = [];
     for (const p of b.patterns ?? []) {
         const f = ctx.projectFiles.find((x) => x.id === p.file);
         try {
             if (f) {
                 const { data } = await projectFileContent(f.projectId, f.id);
-                const name = `patterns/${safeName(f.name.replace(/\.[^.]+$/, ""))}.${extFor(f.mime) === "bin" ? (f.name.split(".").pop() ?? "bin") : extFor(f.mime)}`;
-                await put(join(root, "brand"), name, data);
+                const name = fileName("patterns", f);
+                files.push({ name, data });
+                hash.update(name).update(data);
                 patterns.push({
                     file: name,
                     name: p.name,
@@ -149,11 +139,13 @@ export async function prepareFilmFolder(step, ctx) {
             // a pattern less
         }
     }
+    const logos = [];
     for (const f of ctx.projectFiles.filter((p) => p.kind === "logo")) {
         try {
             const { data } = await projectFileContent(f.projectId, f.id);
-            const name = `logos/${safeName(f.name.replace(/\.[^.]+$/, ""))}.${extFor(f.mime) === "bin" ? (f.name.split(".").pop() ?? "bin") : extFor(f.mime)}`;
-            await put(join(root, "brand"), name, data);
+            const name = fileName("logos", f);
+            files.push({ name, data });
+            hash.update(name).update(data);
             const section = logoSectionLine(b.logoSections, f.id);
             logos.push({
                 file: name,
@@ -165,7 +157,7 @@ export async function prepareFilmFolder(step, ctx) {
             // a logo less
         }
     }
-    await put(join(root, "brand"), "brand.json", JSON.stringify({
+    const json = JSON.stringify({
         note: "The space's brand. Colours are named by what they are for; the first is the accent. A logo's section, a gradient's or a pattern's description says when to use it; colorRules, logoRules and typeRules, where there are any, say how colours, logos and type may be used; text is set in the fonts — a font with `uses` that leave out video is not used in a film: its text gets a system font.",
         name: b.name ?? "",
         about: b.about ?? "",
@@ -199,16 +191,149 @@ export async function prepareFilmFolder(step, ctx) {
             : {}),
         ...(b.textStyles?.length
             ? {
-                textStyles: b.textStyles.map((s) => ({
-                    name: s.name,
-                    style: textStyleLine(s, b.fonts ?? []),
+                textStyles: b.textStyles.map((t) => ({
+                    name: t.name,
+                    style: textStyleLine(t, b.fonts ?? []),
                 })),
             }
             : {}),
         ...(b.typeRules?.length ? { typeRules: ruleLines(b.typeRules).split("\n") } : {}),
         ...(b.logoRules?.length ? { logoRules: ruleLines(b.logoRules).split("\n") } : {}),
         facts: (b.facts ?? []).map((f) => `${f.label}: ${f.value}`),
-    }, null, 1));
+    }, null, 1);
+    const stamp = hash.update(json).digest("hex");
+    let changed = false;
+    try {
+        changed = (await readFile(join(root, BRAND_STAMP), "utf8")) !== stamp;
+    }
+    catch {
+        // A folder from before the stamp: its brand.json tells; a new folder has none.
+        const old = await readFile(join(root, "brand", "brand.json"), "utf8").catch(() => null);
+        changed = old !== null && old !== json;
+    }
+    await rm(join(root, "brand"), { recursive: true, force: true });
+    for (const f of files) {
+        await put(join(root, "brand"), f.name, f.data);
+    }
+    await put(join(root, "brand"), "brand.json", json);
+    await put(root, BRAND_STAMP, stamp);
+    return { changed, stamp };
+}
+const START = join(".engenty", "start");
+const BASE = join(".engenty", "base");
+/**
+ * The brand base: what a film made once from the space's brand for the kit's base (the base's
+ * BRAND.md says what — theme.json at least), kept per space for the kit and the brand as they are.
+ * A changed brand or kit is another key, so it is made again.
+ */
+function brandBaseDir(ctx, kitHash, brandStamp) {
+    const key = createHash("sha256").update(`${kitHash}:${brandStamp}`).digest("hex").slice(0, 24);
+    return join(env.dataDir, "brand-bases", ctx.project.id, key);
+}
+/** What in film/brand/ is the brand base: everything but the brand itself. */
+const isBrandItself = (name) => name === "brand.json" || name === "logos" || name === "patterns";
+/**
+ * Brings the brand into a project that started from a base: brand.json and the logos as they are
+ * now, and the brand base kept for them when there is one. A base that no longer fits the brand
+ * is removed — the film makes it again, as BRAND.md says.
+ */
+async function brandIntoFilm(root, brandChanged) {
+    const base = await readFile(join(root, BASE), "utf8").catch(() => "");
+    if (!base) {
+        return;
+    }
+    const target = join(root, "film", "brand");
+    await mkdir(target, { recursive: true });
+    for (const name of await readdir(target)) {
+        if (isBrandItself(name) || (brandChanged && !existsSync(base))) {
+            await rm(join(target, name), { recursive: true, force: true });
+        }
+    }
+    await cp(join(root, "brand"), target, { recursive: true });
+    if (existsSync(base) && (brandChanged || !existsSync(join(target, "theme.json")))) {
+        await cp(base, target, { recursive: true });
+    }
+}
+/** A new brand is another brand base: the marker points at the one for the brand as it is now. */
+async function refreshBrandBase(root, ctx, step) {
+    if (!existsSync(join(root, BASE))) {
+        return;
+    }
+    const kitHash = ctx.files.find((f) => f.path === step.kit)?.hash ?? "";
+    const stamp = await readFile(join(root, BRAND_STAMP), "utf8");
+    await put(root, BASE, brandBaseDir(ctx, kitHash, stamp));
+}
+/** After a film: keeps what it made from the brand for the next films in this space. */
+export async function keepBrandBase(root) {
+    const base = await readFile(join(root, BASE), "utf8").catch(() => "");
+    const source = join(root, "film", "brand");
+    if (!base || !existsSync(join(source, "theme.json"))) {
+        return;
+    }
+    await rm(base, { recursive: true, force: true });
+    await mkdir(base, { recursive: true });
+    for (const name of await readdir(source)) {
+        if (!isBrandItself(name)) {
+            await cp(join(source, name), join(base, name), { recursive: true });
+        }
+    }
+}
+/** Sets up the folder for a first attempt; a later attempt finds it as it was left. */
+export async function prepareFilmFolder(step, ctx) {
+    const root = filmRoot(ctx.runId, step.id);
+    const brief = renderTemplate(step.brief, ctx.scope).trim();
+    // An earlier film to start from, when it ran.
+    const fromId = step.from ? dataRef(step.from).replace(/^steps\./, "") : null;
+    const fromDir = fromId ? join(filmRoot(ctx.runId, fromId), "film") : null;
+    const from = fromId && fromDir && existsSync(join(fromDir, "index.html")) ? fromId : null;
+    // The same brief and material as last time: the film is there to go on with or to change.
+    const stamp = createHash("sha256")
+        .update(JSON.stringify([
+        brief,
+        Object.values(step.inputs).map((raw) => {
+            const ref = dataRef(raw);
+            const [head, id] = ref.split(".");
+            return head === "steps" ? ctx.state.outputs[id]?.at : ctx.state.values[ref];
+        }),
+        from ? ctx.state.outputs[from]?.at : null,
+    ]))
+        .digest("hex");
+    const stampFile = join(root, ".engenty", "inputs");
+    const same = existsSync(stampFile) && (await readFile(stampFile, "utf8")) === stamp;
+    if (same && existsSync(join(root, "film", "index.html")) && (await savedSession(root))) {
+        // The brand is the space's as it is now, also for a change: colours or a logo may be new.
+        const { changed } = await writeBrand(root, ctx);
+        const start = ((await readFile(join(root, START), "utf8").catch(() => "")) ||
+            "init");
+        if (changed) {
+            await refreshBrandBase(root, ctx, step);
+        }
+        await brandIntoFilm(root, changed);
+        return { root, brief, brandChanged: changed, start };
+    }
+    await rm(root, { recursive: true, force: true });
+    await mkdir(root, { recursive: true });
+    const skills = await placeSkills(step.skills, ctx.files, join(root, ".claude", "skills"));
+    const size = FILM_SIZES[step.format];
+    await put(root, "BRIEF.md", `# Brief\n\nFormat ${step.format}, ${size.width}×${size.height}${step.seconds ? `, about ${step.seconds} s` : ""}. Language of all text on screen: the brief's language.\n\n${brief}\n`);
+    // The style kit: the showcase to look at, and the base a film starts from when it has one.
+    const kitFile = step.kit ? ctx.files.find((f) => f.path === step.kit) : undefined;
+    const base = {};
+    if (kitFile) {
+        const entries = unzipSync(new Uint8Array(await getBlob(kitFile.hash)));
+        for (const [name, data] of Object.entries(entries)) {
+            if (name.endsWith("/")) {
+                continue;
+            }
+            if (name.startsWith("base/")) {
+                base[name.slice("base/".length)] = data;
+            }
+            else {
+                await put(join(root, "showcase"), name.replace(/^showcase\//, ""), data);
+            }
+        }
+    }
+    const { stamp: brandStamp } = await writeBrand(root, ctx);
     // What the run made before.
     const listed = [];
     for (const [name, raw] of Object.entries(step.inputs)) {
@@ -246,12 +371,43 @@ export async function prepareFilmFolder(step, ctx) {
     }
     await put(join(root, "input"), "README.md", `# Material for this film\n\n${listed.join("\n") || "(none)"}\n\nVoice lines play one after another in their order; their lengths decide the timing.\n`);
     await cp(await soundCatalog(), join(root, "audio-catalog"), { recursive: true });
-    // The HyperFrames project, set up for the format.
-    const preset = { "16:9": "landscape", "9:16": "portrait", "1:1": "square" }[step.format];
-    const init = await runHyperframes(["init", "film", "--non-interactive", "--skip-transcribe", `--resolution=${preset}`], { cwd: root, signal: ctx.signal, timeoutMs: 5 * 60_000 });
-    if (init.code !== 0 || !existsSync(join(root, "film"))) {
-        throw new Error(`The film project could not be set up: ${init.out.slice(-300)}`);
+    // The HyperFrames project: the earlier film, the kit's base in this format, or a new one.
+    const index = `index.${step.format.replace(":", "x")}.html`;
+    let start;
+    if (from && fromDir) {
+        start = "from";
+        await cp(fromDir, join(root, "film"), {
+            recursive: true,
+            filter: (path) => !/\/(renders|snapshots)(\/|$)/.test(path.slice(fromDir.length)),
+        });
+        const fromBase = await readFile(join(filmRoot(ctx.runId, from), BASE), "utf8").catch(() => "");
+        if (fromBase) {
+            await put(root, BASE, fromBase);
+        }
     }
+    else if (base[index]) {
+        start = "base";
+        for (const [name, data] of Object.entries(base)) {
+            if (!/^index\.\d+x\d+\.html$/.test(name)) {
+                await put(join(root, "film"), name, data);
+            }
+        }
+        await put(join(root, "film"), "index.html", base[index]);
+        await put(root, BASE, brandBaseDir(ctx, kitFile?.hash ?? "", brandStamp));
+    }
+    else {
+        start = "init";
+        const preset = { "16:9": "landscape", "9:16": "portrait", "1:1": "square" }[step.format];
+        const init = await runHyperframes(["init", "film", "--non-interactive", "--skip-transcribe", `--resolution=${preset}`], { cwd: root, signal: ctx.signal, timeoutMs: 5 * 60_000 });
+        if (init.code !== 0 || !existsSync(join(root, "film"))) {
+            throw new Error(`The film project could not be set up: ${init.out.slice(-300)}`);
+        }
+    }
+    await brandIntoFilm(root, false);
+    const text = rules(step, skills, start);
+    await put(root, "CLAUDE.md", text);
+    await put(root, "AGENTS.md", text);
+    await put(root, START, start);
     await put(root, ".engenty/inputs", stamp);
-    return { root, brief };
+    return { root, brief, brandChanged: false, start };
 }

package/apps/runtime/dist/film/step.js

@@ -2,6 +2,7 @@ import { spawn } from "node:child_process";
 import { existsSync } from "node:fs";
 import { readFile, rm, stat } from "node:fs/promises";
 import { isAbsolute, join, normalize } from "node:path";
+import { FILM_SIZES } from "@engenty-wizards/shared/definition";
 import { note as runNote } from "@engenty-wizards/shared/run";
 import { StepError } from "../engine/types.js";
 import { CLAUDE_BIN, claudeEnv } from "../harness/claude.js";
@@ -9,7 +10,7 @@ import { failureOf } from "../harness/model.js";
 import { openBridge } from "../mcp/bridge.js";
 import { saidOf } from "../model-errors.js";
 import { filmClient } from "../models.js";
-import { prepareFilmFolder, savedSession, saveSession } from "./project.js";
+import { keepBrandBase, prepareFilmFolder, savedSession, saveSession } from "./project.js";
 import { runHyperframes } from "./tools.js";
 /**
  * A film step: the installed client (Claude Code) works in the film's folder with the skills,
@@ -99,7 +100,7 @@ export async function runFilmStep(step, ctx) {
     }
     const { client, alias } = found;
     await ctx.emit("info", { code: "filmSetup" });
-    const { root, brief } = await prepareFilmFolder(step, ctx);
+    const { root, brief, brandChanged, start } = await prepareFilmFolder(step, ctx);
     const resume = await savedSession(root);
     await ctx.emit("info", resume ? { code: "filmResume" } : { code: "filmClient", params: { client: client.name } });
     const limit = AbortSignal.any([ctx.signal, AbortSignal.timeout(LIMIT_MS)]);
@@ -244,11 +245,20 @@ export async function runFilmStep(step, ctx) {
     try {
         // A review's note asks for a change: the film's code is there, so it is edited, not redone.
         const note = ctx.state.notes[step.id]?.trim();
+        // A brand changed in the space since the film was made: the film's code carries the old one.
+        const brandNote = !brandChanged
+            ? ""
+            : start === "init"
+                ? "\n\nThe space's brand has changed since the film was made: brand/brand.json and brand/logos/ are new. Carry them into the film wherever it uses the brand (its own copies included), so every colour, logo and name is the new one, and check the frames for contrast."
+                : "\n\nThe space's brand has changed since the film was made: film/brand/brand.json and the logos are new. If film/brand/theme.json is missing, make it again as film/BRAND.md says. Make sure every colour, logo and name in the film is the new one, and check the frames for contrast.";
+        const size = FILM_SIZES[step.format];
         const prompt = resume && note
-            ? `The person watched the film and asks for this change:\n\n${note}\n\nChange the film in film/ accordingly — keep what they did not mention — check the frames again, and end with a short summary of what you changed.`
+            ? `The person watched the film and asks for this change:\n\n${note}${brandNote}\n\nChange the film in film/ accordingly — keep what they did not mention — check the frames again, and end with a short summary of what you changed.`
             : resume
-                ? "Carry on with the film where you stopped. Read PROGRESS.md and the folder to see where that was, then finish it."
-                : `Make the film BRIEF.md asks for, following CLAUDE.md.\n\n${brief}`;
+                ? `Carry on with the film where you stopped. Read PROGRESS.md and the folder to see where that was, then finish it.${brandNote}`
+                : start === "from"
+                    ? `film/ holds this run's film in another format. Lay it out for ${step.format} (${size.width}×${size.height}), following CLAUDE.md: set the size of film/index.html, then make every scene fit — scenes, timing, words and sound stay. Check the frames, render a draft, and end with a short summary of what you changed.\n\nThe brief, for reference:\n\n${brief}`
+                    : `Make the film BRIEF.md asks for, following CLAUDE.md.\n\n${brief}`;
         const first = await turn(prompt, resume);
         summary = typeof first.result === "string" ? first.result.trim() : "";
         // The final render is ours: it does not depend on the client still running. What fails
@@ -277,6 +287,7 @@ export async function runFilmStep(step, ctx) {
     finally {
         bridge.close();
     }
+    await keepBrandBase(root).catch(() => { });
     const ref = await ctx.saveAsset({
         stepId: step.id,
         kind: "video",