acrylblends 1.0.10 → 1.2.0

package/docs/framework/workshop/facilitator.md

@@ -1,108 +1,99 @@
-# Facilitator notes: the 90-minute ACRYL Blends workshop
+# Facilitator notes: building inside the ACRYL frame
 
-Read the attendee handout first (`docs/framework/workshop/README.md`); this page is the room around it: what to put on each machine, what actually breaks, and
-where to cut when the clock runs. Every timing and every failure below was measured on the published `acrylblends` 1.0.0 during the readiness walk
-(`docs/plans/workshop-readiness.md`).
+Read the handout first (`docs/framework/workshop/README.md`); this page is the room around it. The workshop changed shape again for the frame: the
+app is created, then **opened inside ACRYL's IDE** (projects on the left, the app's page in the canvas, files/changes/terminals on the right), a
+chat model works on the app from inside the frame, and coding agents run in terminal tabs in the same folder. The data layer, the desktop window and
+the panel-first flow of the previous handout are gone.
+
+The handout is written for **acrylblends 1.2.0 or newer** (the release that carries the frame). A room on an older release is on the previous handout;
+check with `npx acrylblends@latest --version` before the day.
 
 ## Before the room: put this on every machine
 
 | What | Why | How |
 | --- | --- | --- |
-| Node.js 22.19 or newer (24 LTS or 26 tested), npm 11 | the app runs TypeScript directly, no build step | `node -v`; if missing, the LTS from nodejs.org or `brew install node` (Node 26 today, which is tested) |
-| git | the registry block clones the registry | `git --version` |
-| A warm npm cache | the first `npm create` downloads the initializer, `npm install` downloads Electron | create one app and add the desktop shell once per machine (below) |
-| A coding agent, logged in | step 7 drives Codex or Claude Code through the panel | `codex login status` or run `claude` once |
-| `~/acryl-workshop/prepared/` | the no-network fallback and the reset | copy the two prepared apps (below) |
-| A GitHub account with `gh auth login` | step 10 forks the workshop registry and opens a pull request | `gh auth status` |
-| A device with `git` and a text editor | the edits in steps 2, 4 and 8 are small but real | `git --version` |
-
-Warm-up, once per machine (this is also the exact smoke test that the room works):
-
-```sh
-mkdir -p ~/acryl-workshop && cd ~/acryl-workshop
-npm create acrylblends@latest warmup notes
-cd warmup && npm install && npm test
-npx acrylblends add desktop && npm install
-cd ~/acryl-workshop && cp -R warmup prepared-notes && rm -rf warmup
-```
-
-That leaves `prepared-notes` with everything installed, including Electron.
-
-## Timings, checkpoints, and what to make optional
-
-The handout's own timings, as measured on the published 1.0.2 (macOS, cold npm cache in a throwaway home):
-
-| Minutes | Step | Measured | If late |
+| The preflight passing | it checks Node, npm, git, an agent with its login or key, a free port, and on Windows PowerShell and long paths | `npx acrylblends@latest preflight` ends with `Ready for the workshop.` |
+| Node.js 22.19 or newer (24 and 26 tested) | the app runs TypeScript directly | `node -v`; the app's `scripts/check-node.cjs` refuses an older Node with a clear line |
+| git, and a GitHub account with `gh auth login` | the first `npm run dev` makes the folder a git repository (Files and Changes need one); the last block forks the registry | `git --version`, `gh auth status` |
+| One coding agent, logged in | block 5 starts it in a terminal tab; `claude`, `codex` and `pi` all worked | `codex login` once, or run `claude` once, or pi with `DEEPSEEK_API_KEY` in the terminal that starts `npm run dev` |
+| One model key | block 3 adds it in Settings > Models; without it the chat shows a connect card | a DeepSeek key from <https://platform.deepseek.com>, or a Claude/ChatGPT subscription through Sign in with an account |
+| A prepared app with `npm install` done | the first install brings the frame and the chat engine (about 500 MB together); a room on one Wi-Fi should not do it 20 times | run the handout's block 1 once per machine and keep the folder as `~/acryl-workshop/prepared/` |
+| A warm npm cache | the first install dominates block 1 | the prepared app does it |
+
+**The agent setting that decides the day.** The agents are configured to act rather than describe. Check on every machine that a plain request
+produces files, not a plan: ask the prepared app's chat "add a line to the app's page" and watch the Changes panel. If it only describes, the model
+is waiting for permission; the handout's sentence is "do it now".
+
+**Agent-specific checks.** Codex answering `model_not_found` means the account does not have the default model: pick one it supports (`/model` in
+codex, or `model = "..."` in `~/.codex/config.toml`). pi with DeepSeek needs `DEEPSEEK_API_KEY` in the environment of the terminal that runs `npm
+run dev` (the terminal tabs inherit it); the preflight reports `PASS agent pi (DeepSeek key found)`. The package is
+`@earendil-works/pi-coding-agent`.
+
+## Timings, from the rehearsal (this Mac, packed CLI, isolated HOME)
+
+| Minutes | Block | Measured | If late |
 | --- | --- | --- | --- |
-| 0-10 | installs and checks | seconds each | never cut |
-| 10-15 | create and run the blank app | create 9 s cold (2 s warm), install 2 s, boot 2 s | never cut |
-| 15-22 | change one route | reload is instant | never cut |
-| 22-30 | tests and the typecheck | test 0.5-2 s, check 2.5-4 s | keep; cut the "write a test" exercise |
-| 30-38 | data: JSON then SQLite (**optional**) | two adds plus edits, ~8 min | **cut first** |
-| 38-45 | the desktop window | add 2 s, install 3 s, first Electron boot ~20 s | pre-warm Electron on every machine or demo it |
-| 45-53 | pull a starter | create 4 s, install 3 s, runs at once | keep; it is the fastest win in the room |
-| 53-60 | create from a template | create + install + add desktop 4 s | drop the second app |
-| 60-75 | the agent builds a feature | set-up 4 s; codex wrote a page and tests in about 7 minutes | never cut; demo it if the room is behind |
-| 75-82 | upgrade | seconds: a fresh app answers "everything is up to date" | keep; it is a 2-minute talk |
-| 82-90 | publish and the hero moment | the registry steps are seconds; the PR is talk | always keep at least the hero talk |
-
-Checkpoints in the handout, and what to look for as you walk the room: **15 minutes** every screen shows `{"app":"my-hero","ok":true}`; **45 minutes**
-every screen has the app in a desktop window; **75 minutes** every screen has `/board` open with the agent's page. A machine behind at a checkpoint is
-what the optional column is for, and the handout names the same choices so nobody has to guess.
-
-## What breaks in the room, and what to say
-
-These are the defects found by the walk. They are known; say so rather than letting people think they broke something.
-
-- **An agent with its own settings acts differently.** Skills, hooks and instructions in a person's own Codex or Claude configuration travel into the panel's run: on the owner's laptop Codex stopped to "present a design for approval" instead of building. Word every task for the agent as "do it now, without asking for approval", and for a demo machine start the agent from a clean configuration (a fresh `CODEX_HOME`, no personal skills).
-- **The data step is the slow one.** Wiring `kv` then `db` by hand is about ten minutes of edits for a newcomer (two rows, two registry lines, two
-  type imports, the migrations folder). It is the block the handout names optional, and the one to help with first.
-- **A relative migrations path in `blend.yaml` fails.** `migrations: migrations` in the row stops the app with "this app has no file base URL to
-  resolve it from". The folder is named in `src/app.ts`'s compose options instead; the handout teaches that form and the stuck line names the error.
-- **`pi` shows up only when the app can see its login.** 1.0.2 offers pi as a chat driver when `DEEPSEEK_API_KEY` is exported or `~/.pi/agent/auth.json`
-  holds a deepseek entry, read from the HOME the app runs in. On a normal attendee machine it is there; in a run with a moved HOME it is not (and pi
-  would fail on its first message anyway). `pty:pi` needs only the program.
-- **The agent run takes minutes, not seconds.** Codex wrote the page and its tests in about seven; tell the room to start it and keep talking.
-- **Publishing.** The workshop registry is `github.com/acryldev/workshop-2026-11-20`, public and open. Attendees fork it, run
-  `node scripts/make-entry.mjs ../agent-app <login>.agent-app --description "..."`, push and open a pull request; a check merges it, usually well under
-  two minutes, and a refusal comes as a comment. Taking an app down is a pull request that removes its folder. Pulling is
-  `--from <id> --registry github:acryldev/workshop-2026-11-20` (rehearsed on 1.0.2: create 12 s, install 3 s, runs at once).
-- **Browser-only attendees (TODO(M9)).** The handout's hosted-workspace stub is empty until M9 is live; until then a browser-only attendee can follow
-  along but not create an app.
-- **node-pty's install script (C5).** `npm install` warns that npm 11 blocked `node-pty`'s script. The terminal drivers still list; the workshop does
-  not open one.
+| 0-10 | preflight and setup | preflight ~15 s; the prepared app skips create and install | never cut |
+| 10-20 | create and open the frame | the first `npm install` dominates (the frame and the chat engine); the frame's first page is up in a few seconds after that | use the prepared app and open its frame |
+| 20-25 | the first change at /app | the Files view opens `src/routes.ts`; stop and `npm run dev` reconnects the frame in a few seconds; the page shows the edit | cut `npm test` to the take-home |
+| 25-30 | Settings > Models | the key saves with Apply (`Saved DeepSeek (deepseek-official).`); the page uses it after a reload | paste the key in the first-run card instead, Save and continue |
+| 30-50 | chat builds the board | the chat writes into the app folder and Changes fills; the restart loop shows it at /app/board | if the model is slow, cut the board to one column |
+| 50-65 | a coding agent in a terminal | the agent tab starts in the app folder (its prompt is `my-app`); `.acryl/bin/acryl look` prints the page in the frame's tile | demo one agent and let the room follow |
+| 65-80 | upgrade an older app | `npx acrylblends@latest upgrade` reports every file it changed (the `frame` line is the new layout), then `npm install` and `npm run dev` | keep the report, skip the second app |
+| 80-90 | publish (take-home) | the registry check merges in about two minutes | leave it as the take-home |
+
+What the rehearsal verified end to end on this Mac: a packed CLI in an isolated HOME, the app opened by the frame with the app's page in a tab
+(the first-run tile), the Preview Notice dismissed once, Settings > Models saving a key and the chat sending with it (against a local mock), a
+terminal tab running commands in the app folder, the app's page edited and shown after a restart, the door seeing the page (`acryl look`), and an
+app made by the previous release upgraded and opened by the frame.
+
+## What to say in the room
+
+- **The frame is the product.** The point is not "an app with a chat sidebar"; it is that ACRYL's IDE hosts the app you are building: the app is
+  the page in the middle, its folder is the workspace, and the agents work in that folder.
+- **Settings > Models is the key's home.** The key goes to the frame's own credentials store, never the app folder or `.acrylblends` files. The
+  first-run card writes the same store; either path is fine.
+- **The loop is stop, start, look.** A source change needs `npm run dev` again; the port is stable per app, so the frame reconnects on the same
+  address and the app's tab is still there. If a chat tab comes to the front after the restart, press the `my-app` tab.
+- **Two kinds of agent.** The chat (DSH's own, in the frame) and the coding agents in terminal tabs are different hands on the same folder; show
+  both and let people pick.
+- **The door.** `.acryl/bin/acryl look` prints the page with refs, `act` clicks and types. In the frame the page is the tile, and the door sees
+  it. This is how an agent checks its own work.
+- **Production is unchanged.** The frame, the chat and the agents are development tools; `NODE_ENV=production npm start` serves the app alone.
+
+## Windows
+
+Windows PowerShell 5.1 has no `&&` (two lines, or `;`); PowerShell sets variables with `$env:NAME="value"`; cmd.exe's `Ctrl-C` asks `Terminate
+batch job (Y/N)?` (answer `Y`); cmd.exe does not expand `~` (use `%USERPROFILE%`). `npm install` needs the "Desktop development with C++" workload
+of Visual Studio Build Tools for the terminal package; the preflight notes it.
 
 ## The no-network fallback
 
-If the venue has no reliable network:
-
-1. Every machine gets `prepared-notes` and a prepared agent app from the sheet above, so steps 1-6 skip creation and installs.
-2. Step 8 uses the cloned registry and the installed `blends-core`; no network needed.
-3. Step 7 needs the agent's own model, so it cannot run offline. Demo it from your machine on a tethered connection, or record it (a 4-minute
-   screen recording of the codex run is enough).
-4. Keep one machine on a phone hotspot for `npm create` failures.
+1. Prepared apps with `npm install` done cover blocks 1, 2 and the frame; the models (chat and agents) still need a connection or a demo.
+2. Block 7's registry needs GitHub; if the venue is offline, publish from your machine on a hotspot at the end, or show the recording.
+3. Keep one phone hotspot for the room.
 
-## Demo script for the agent block (5 minutes, if you demo instead of hands-on)
+## Demo script (five minutes, if the room is behind)
 
-1. On the prepared agent app: `npm run dev`, open the page, click the panel button.
-2. Ask: "Add a route GET /agent-built to src/routes.ts that returns {\"built\": true}, then run the tests and tell me what happened."
-3. Narrate while it runs: the agent reads `AGENTS.md`, reads `docs/framework`, edits `src/routes.ts`, runs the tests; the terminal prints
-   `Change detected … Restarting`; reload `/agent-built` and show `{"built":true}`.
-4. Point at the panel's stop button and the audit line the panel writes under `.acrylblends/audit/`.
+1. Prepared app, frame open on the app's page: press `+`, open **AcrylDSH Chat**, ask for a sentence on the page. Narrate the Changes panel and
+   the restart loop.
+2. Open a **files** tab in the right panel and show the edit the model made.
+3. `+` → **Pi** (or Claude): the agent starts in the app folder; ask it for a route; run `.acryl/bin/acryl look` in that terminal and show the
+   page's snapshot.
+4. Settings > Models: show where the key lives and that it is not in the app folder.
+5. Show the registry listing with an app already published.
 
 ## Resetting between sessions
 
-Everything a person makes lives inside their app folder and `~/acryl-workshop`. To reset a machine:
-
-```sh
-rm -rf ~/acryl-workshop/[a-z]*-app ~/acryl-workshop/registry
-cp -R ~/acryl-workshop/prepared/* ~/acryl-workshop/    # if you keep a prepared/ folder
-```
-
-Nothing is installed globally except the agent and Bun; neither needs cleaning between sessions.
+Everything a person makes lives inside their app folder and `~/acryl-workshop`. To reset a machine, delete the app folders and copy the prepared one
+back; nothing is installed globally except the agent, `gh` and Node. An app's data lives in its `.acrylblends/` (gitignored); the model key lives in
+that home's credentials store, so a fresh copy starts without it.
 
 ## What is still open
 
-- Starter pull (B1), the panel's rows (C1) and the upgrade command in the docs (B2) are with the framework team; when they land, the handout's
-  TODO lines become normal steps and this page's "what breaks" list shrinks.
-- The Windows and Linux runs of the attendee handout are being replayed separately; add what differs to the handout's OS column rather than here.
+- The frame's chat tab takes the focus when it binds its session after a restart; the app's tab is one click away and the guide says so.
+- The frame's address is stable across restarts: the launcher keeps the token in the app home (owner-only, atomic) and reuses it, so an open page
+  comes back by reloading its URL even if the browser lost its cookie. `npx acrylblends open` prints the address of the running frame;
+  `npx acrylblends open --new` rotates it (the old address stops working at once and the new one is printed). The frame-side banner that names the
+  command is still to come (after the 120 gate work).
+- The one-click WebBoxes.ai deploy and the browser-only section stay TODO(M9) until that workspace is live.

package/legacy/README.md

@@ -0,0 +1,9 @@
+# The scaffolds published acrylblends releases shipped
+
+Generated by `scripts/build-legacy-layouts.mjs`; do not edit by hand. Each folder is a template, each hash under it one distinct scaffold (deduplicated by
+content hash across releases), and `layouts.json` maps every published release that shipped templates (0.3.0 through 1.1.0, 40 releases)
+to the layouts it shipped.
+
+`acrylblends upgrade` compares an app's scaffold files with these bytes: a file the app has not edited is brought up to date, an edited one is refused (or
+replaced with --force after a backup). Releases before 0.7.8 wrote src/main.ts importing './plugins/...', which cannot start; their layouts are kept so the
+upgrade can say so precisely instead of writing a frame such a release's app cannot run.

package/legacy/agent/157ce3db1112/src/app.ts

@@ -0,0 +1,98 @@
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { Context, type Fiber } from '@deepseek-ai/cordis'
+import * as nodeServer from './plugins/acryl-node-server/src/index.ts'
+import * as router from './plugins/acryl-router/src/index.ts'
+import * as state from './plugins/acryl-state/src/index.ts'
+import { agent, memory, model, tools } from './plugins/agent/index.ts'
+import { builder } from './plugins/builder/index.ts'
+import { extensions } from './plugins/extensions/index.ts'
+import { type AppInstance, instance } from './plugins/instance/index.ts'
+import {
+  blueprintsIn,
+  compose,
+  loadManifest,
+  type ParameterValue,
+} from './plugins/manifest/index.ts'
+import { type OpenAIConfig, openai } from './plugins/openai/index.ts'
+import { sandboxPlugin } from './plugins/sandbox/index.ts'
+import { save } from './plugins/save/index.ts'
+import { tasks } from './plugins/tasks/index.ts'
+import { routes } from './routes.ts'
+
+/** The plugins this app's code provides. `blend.yaml` chooses, orders and configures them. */
+export const registry = {
+  tasks,
+  model,
+  tools,
+  memory,
+  agent,
+  'acryl-router': router,
+  'acryl-state': state,
+  extensions,
+  builder,
+  save,
+  sandbox: sandboxPlugin,
+  routes,
+  'acryl-node-server': nodeServer,
+}
+
+/** The manifest next to this app's source. */
+export const MANIFEST = join(fileURLToPath(new URL('..', import.meta.url)), 'blend.yaml')
+
+/**
+ * The app's manifest, resolved. A Blend finds its Blueprint in `blueprints/<id>.yaml`; an app that is itself a Blueprint never looks.
+ * `createApp` and the tests read it the same way.
+ */
+export function readManifest(values?: Readonly<Record<string, ParameterValue>>) {
+  return loadManifest(MANIFEST, {
+    known: Object.keys(registry),
+    getBlueprint: blueprintsIn(join(fileURLToPath(new URL('..', import.meta.url)), 'blueprints')),
+    ...(values ? { values } : {}),
+  })
+}
+
+export interface App {
+  readonly root: Context
+  readonly url: string
+  stop(): Promise<void>
+}
+
+/**
+ * The app: `instance` first (where it lives, chosen at run time), then the manifest's rows in order. The app's own `extensions/`
+ * folder is trusted to install at start, and is where the builder writes.
+ */
+export async function createApp(
+  chosen: AppInstance,
+  options: {
+    values?: Readonly<Record<string, ParameterValue>>
+    /** A real model (any OpenAI-compatible API) in place of the offline scripted one. */
+    model?: OpenAIConfig
+  } = {},
+): Promise<App> {
+  const manifest = readManifest(options.values)
+  const extensionsDir = join(chosen.root, 'extensions')
+  const root = new Context()
+  const first = root.plugin(instance, chosen)
+  await first.await()
+  const fibers: Fiber[] = [
+    first,
+    // The `model` row mounts the scripted model, or the real one when a model is configured.
+    ...(await compose(root, manifest, options.model ? { ...registry, model: openai } : registry, {
+      ...(options.model ? { model: { ...options.model } } : {}),
+      // Runtime values the manifest cannot hold: the manifest's own digest (every task records it), and who may install.
+      tasks: { manifest: `sha256:${manifest.digest}` },
+      // The `approval` parameter in blend.yaml (the extensions row) turns this source into one that asks.
+      extensions: { sources: [{ dir: extensionsDir, trust: 'install' }] },
+      builder: { dir: extensionsDir },
+      server: { port: chosen.port.start, scan: chosen.port.scan ? 20 : 0, hostname: chosen.host },
+    })),
+  ]
+  return {
+    root,
+    url: root.nodeServer.url,
+    async stop() {
+      for (const fiber of [...fibers].reverse()) await fiber.dispose()
+    },
+  }
+}

package/legacy/agent/157ce3db1112/src/routes.ts

@@ -0,0 +1,63 @@
+import type { Context } from '@deepseek-ai/cordis'
+import { Acryl } from './plugins/acryl-router/src/index.ts'
+import { bodyLimit } from './plugins/acryl-router/src/middleware/index.ts'
+import type {} from './plugins/agent/index.ts'
+import type {} from './plugins/extensions/index.ts'
+import type {} from './plugins/tasks/index.ts'
+
+export const APP_NAME = '__APP_NAME__'
+
+/**
+ * The app's own routes on the router: `POST /ask` for the agent; `GET /extensions` and `GET /tasks` to observe what it did (every run is a
+ * durable task owning one task per tool call); `POST /tasks/cancel`. What changes is also streamed: `GET /api/state/tasks/events` and
+ * `GET /api/state/extensions/events`. The mount is removed when the plugin is disposed.
+ */
+export const routes = {
+  name: 'routes',
+  inject: ['router', 'agent', 'extensions', 'tasks'],
+  apply(ctx: Context) {
+    // A body here is a name, an id or a question; anything bigger is refused before it is read.
+    const json = async (c: {
+      req: { json(): Promise<unknown> }
+    }): Promise<Record<string, unknown>> => {
+      const body = await c.req.json().catch(() => undefined)
+      return typeof body === 'object' && body !== null ? (body as Record<string, unknown>) : {}
+    }
+    const app = new Acryl()
+      .use(bodyLimit({ maxSize: 64 * 1024 }))
+      .get('/', (c) => c.json({ app: APP_NAME, ok: true }))
+      .get('/health', (c) => c.json({ ok: true }))
+      .get('/extensions', (c) =>
+        c.json({
+          installed: ctx.extensions.list(),
+          notInstalled: ctx.extensions.pending(),
+          waitingForApproval: ctx.extensions.approvals(),
+        }),
+      )
+    // The owner's decision on an install that is waiting (the `approval` parameter in blend.yaml).
+    for (const [path, decide] of [
+      ['/extensions/approve', (name: string) => ctx.extensions.approve(name)],
+      ['/extensions/deny', (name: string) => ctx.extensions.deny(name)],
+    ] as const) {
+      app.post(path, async (c) => {
+        const { name } = await json(c)
+        if (typeof name !== 'string') return c.json({ error: 'name must be a string' }, 400)
+        return c.json(await decide(name))
+      })
+    }
+    app
+      .get('/tasks', (c) => c.json(ctx.tasks.list().slice(0, 100)))
+      .post('/tasks/cancel', async (c) => {
+        const { id } = await json(c)
+        if (typeof id !== 'string' || !ctx.tasks.get(id))
+          return c.json({ error: 'no such task' }, 404)
+        return c.json({ cancelled: ctx.tasks.cancel(id) })
+      })
+      .post('/ask', async (c) => {
+        const { question } = await json(c)
+        if (typeof question !== 'string') return c.json({ error: 'question must be a string' }, 400)
+        return c.json(await ctx.agent.run(question))
+      })
+    ctx.router.route('/', app)
+  },
+}

package/legacy/agent/24c681a00fca/src/app.ts

@@ -0,0 +1,160 @@
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { Context, type Fiber } from '@deepseek-ai/cordis'
+import * as door from '../plugins/acryl-door/src/index.ts'
+import * as nodeServer from '../plugins/acryl-node-server/src/index.ts'
+import * as router from '../plugins/acryl-router/src/index.ts'
+import * as state from '../plugins/acryl-state/src/index.ts'
+import { agent, memory, model, tools } from '../plugins/agent/index.ts'
+import * as panel from '../plugins/agent-panel/index.ts'
+import { builder } from '../plugins/builder/index.ts'
+import { extensions } from '../plugins/extensions/index.ts'
+import { type AppInstance, instance } from '../plugins/instance/index.ts'
+import {
+  blueprintsIn,
+  compose,
+  loadManifest,
+  type ParameterValue,
+} from '../plugins/manifest/index.ts'
+import { type OpenAIConfig, openai } from '../plugins/openai/index.ts'
+import { sandboxPlugin } from '../plugins/sandbox/index.ts'
+import { save } from '../plugins/save/index.ts'
+import { tasks } from '../plugins/tasks/index.ts'
+import { routes } from './routes.ts'
+
+/** The plugins this app's code provides. `blend.yaml` chooses, orders and configures them. */
+export const registry = {
+  tasks,
+  model,
+  tools,
+  memory,
+  agent,
+  'acryl-router': router,
+  'acryl-state': state,
+  extensions,
+  builder,
+  save,
+  sandbox: sandboxPlugin,
+  routes,
+  'acryl-node-server': nodeServer,
+  'agent-panel': panel,
+  'acryl-door': door,
+}
+
+/** The manifest next to this app's source. */
+export const MANIFEST = join(fileURLToPath(new URL('..', import.meta.url)), 'blend.yaml')
+
+/**
+ * The app's manifest, resolved. A Blend finds its Blueprint in `blueprints/<id>.yaml`; an app that is itself a Blueprint never looks.
+ * `createApp` and the tests read it the same way.
+ */
+export function readManifest(values?: Readonly<Record<string, ParameterValue>>) {
+  return loadManifest(MANIFEST, {
+    known: Object.keys(registry),
+    getBlueprint: blueprintsIn(join(fileURLToPath(new URL('..', import.meta.url)), 'blueprints')),
+    ...(values ? { values } : {}),
+  })
+}
+
+export interface App {
+  readonly root: Context
+  /** The address the server listens on; empty when the app was made with `listen: false`. */
+  readonly url: string
+  stop(): Promise<void>
+}
+
+/** The development rows production leaves out, and what each one gives a visitor. */
+const DEVELOPMENT_ROWS: Record<string, string> = {
+  agent: 'POST /ask runs the agent, which spends the model key and calls its tools',
+  builder: 'the agent can write plugin source into plugins/',
+  extensions:
+    'a plugin installed live runs in this process, and POST /extensions/approve decides installs',
+}
+
+/**
+ * The app: `instance` first (where it lives, chosen at run time), then the manifest's rows in order. The app's `plugins/`
+ * folder is trusted to install at start, and is where the builder writes.
+ */
+export async function createApp(
+  chosen: AppInstance,
+  options: {
+    values?: Readonly<Record<string, ParameterValue>>
+    /** A real model (any OpenAI-compatible API) in place of the offline scripted one. */
+    model?: OpenAIConfig
+    /** Start the HTTP server (default). Tests pass `false` and call `app.root.router.request(path)`: it needs no port, so it also runs where a sandbox forbids listening. */
+    listen?: boolean
+  } = {},
+): Promise<App> {
+  const read = readManifest(options.values)
+  // Rows left out: the server (and so the door, which needs it) when the app is reached in process; the door in production and with ACRYL_DOOR=off (one process at a time
+  // serves a folder's door, so the tests that start several apps set it).
+  const listen = options.listen !== false
+  const leaveOut = new Set<string>()
+  if (!listen) leaveOut.add('acryl-node-server').add('acryl-door')
+  if (process.env.NODE_ENV === 'production' || process.env.ACRYL_DOOR === 'off')
+    leaveOut.add('acryl-door')
+  // Production: the rows that give a visitor power over the running app or the owner's model key are left out too. The agent (`POST /ask` spends the model key and runs tools),
+  // the builder and the extensions (live plugin install runs code in this process, and `POST /extensions/approve` decides it) are development tools. `ACRYL_PRODUCTION_KEEP`
+  // names the ones to keep (`agent,builder,extensions`); each one kept is announced at start, because none of them is behind a login.
+  if (process.env.NODE_ENV === 'production') {
+    const keep = new Set(
+      (process.env.ACRYL_PRODUCTION_KEEP ?? '')
+        .split(',')
+        .map((name) => name.trim())
+        .filter((name) => name !== ''),
+    )
+    for (const name of keep)
+      if (!(name in DEVELOPMENT_ROWS))
+        console.warn(
+          `WARNING: ACRYL_PRODUCTION_KEEP names "${name}", which is not one of ${Object.keys(DEVELOPMENT_ROWS).join(', ')}`,
+        )
+    for (const [row, danger] of Object.entries(DEVELOPMENT_ROWS)) {
+      if (keep.has(row))
+        console.warn(
+          `WARNING: the "${row}" row runs in production because ACRYL_PRODUCTION_KEEP names it: ${danger}. Nothing here is behind a login; put the app behind your own.`,
+        )
+      else leaveOut.add(row)
+    }
+  }
+  const manifest = {
+    ...read,
+    plugins: read.plugins.map((row) => (leaveOut.has(row.use) ? { ...row, disabled: true } : row)),
+  }
+  const extensionsDir = join(chosen.root, 'plugins')
+  // One release of grace: an app made before 0.7.8 kept what the agent wrote in `extensions/`. It is still installed, with a warning.
+  const legacyDir = join(chosen.root, 'extensions')
+  const legacy = existsSync(legacyDir)
+  if (legacy)
+    console.warn(
+      'warning: extensions/ is the old folder for plugins the agent writes; move them to plugins/ ("git mv extensions/<name> plugins/<name>"). extensions/ is read for this release only.',
+    )
+  const root = new Context()
+  const first = root.plugin(instance, chosen)
+  await first.await()
+  const fibers: Fiber[] = [
+    first,
+    // The `model` row mounts the scripted model, or the real one when a model is configured.
+    ...(await compose(root, manifest, options.model ? { ...registry, model: openai } : registry, {
+      ...(options.model ? { model: { ...options.model } } : {}),
+      // Runtime values the manifest cannot hold: the manifest's own digest (every task records it), and who may install.
+      tasks: { manifest: `sha256:${manifest.digest}` },
+      // The `approval` parameter in blend.yaml (the extensions row) turns this source into one that asks.
+      extensions: {
+        sources: [
+          { dir: extensionsDir, trust: 'install' },
+          ...(legacy ? [{ dir: legacyDir, trust: 'install' as const }] : []),
+        ],
+      },
+      builder: { dir: extensionsDir },
+      server: { port: chosen.port.start, scan: chosen.port.scan ? 20 : 0, hostname: chosen.host },
+    })),
+  ]
+  return {
+    root,
+    url: listen ? root.nodeServer.url : '',
+    async stop() {
+      for (const fiber of [...fibers].reverse()) await fiber.dispose()
+    },
+  }
+}