acrylblends 1.0.9 → 1.1.0

package/docs/framework/workshop/README.md

@@ -1,191 +1,164 @@
-# From nothing to your own app: the ACRYL Blends workshop
+# An app that builds and drives itself: the ACRYL Blends workshop
 
-Ninety minutes, starting from an empty folder. **Acryl** is a small web framework built on Web Standards: a handler takes a `Request` and returns a
-`Response`, exactly as in the browser. **ACRYL Blends** puts that framework inside an app you own: a folder whose `blend.yaml` lists its plugins, whose
-`plugins/` folder holds their code, and which runs in a browser or in a desktop window. A coding agent can change the app while it runs. By the end you
-will have built an app from the blank template, added a feature to it with an agent, opened it as a desktop window, upgraded it, and published it as a
-starter other people can pull from the registry.
+Ninety minutes, from an empty folder to an app whose interface a coding agent built from inside it, then drove the way a person would: it opens the
+sidebar, ticks a card, changes a setting. The same app then runs in a desktop window, where the agent drives that too, and you publish it as a starter
+other people can pull. **Acryl** is the small web framework underneath (a handler takes a `Request` and returns a `Response`); **ACRYL Blends** is the app
+around it: a folder of Cordis plugins with a `blend.yaml`, running on your machine, with an agent living inside its panel.
 
-Every command below is copy-pasteable and was run on the published packages. Each step says how long it takes; the checkpoints tell you whether you
-are on time.
+Two things make this workshop different from clicking through a tutorial: you write very little code (the agent writes the interface, you direct and
+edit it), and the agent is not a sidebar chat about the code, it is a hand on the app.
 
-## What you need (10 minutes)
+This guide is for **acrylblends 1.0.10 or newer**; `npm create acrylblends@latest` gives you that.
 
-| | macOS | Windows | Linux |
-| --- | --- | --- | --- |
-| Node.js 22.19 or newer (24 LTS or 26 tested) | `node -v` | `node -v` | `node -v` |
-| npm, which comes with Node | `npm -v` | `npm -v` | `npm -v` |
-| git | `git --version` | `git --version` | `git --version` |
-| a coding agent, logged in | `codex login status` or `claude --version` | same | same |
-| a GitHub account and the `gh` CLI, logged in | `gh auth status` | same | same |
+## 0. Before you start (10 minutes)
 
-Install what is missing: Node from <https://nodejs.org> (the LTS), git from <https://git-scm.com>, the GitHub CLI (`brew install gh`, `winget
-install GitHub.cli`, or <https://cli.github.com>), and one agent with `npm i -g @openai/codex` (then `codex login` once) or Claude Code. Run
-`gh auth login` once, in any repository: step 10 publishes your app with a pull request. No prior knowledge of ACRYL, Cordis or Blends is needed;
-every new word is explained where it appears.
-
-Make a folder and open a terminal in it:
+Run this first. It checks everything below and prints one line per check, with the exact command for anything missing:
 
 ```sh
-mkdir ~/acryl-workshop && cd ~/acryl-workshop
+npx acrylblends@latest preflight
 ```
 
-## The path
+It ends with `Ready for the workshop.`, or with how many lines say `FIX`: run each `FIX` line, then the preflight again. `NOTE` lines are things the
+first blocks do without (`gh` is only needed in block 5).
 
-| Minutes | Step | What you get |
-| --- | --- | --- |
-| 0-10 | Before you start | tools installed and checked |
-| 10-15 | 1. Create and run | a blank app answering in a browser |
-| 15-22 | 2. Change one thing | a route of your own, live, without a restart |
-| 22-30 | 3. Tests and the typecheck | the app proves itself |
-| 30-38 | 4. Data: JSON, then SQLite *(optional)* | a counter kept in a file, then in SQL |
-| 38-45 | 5. A desktop window | the same app as a window |
-| 45-53 | 6. Pull a starter from the registry | someone else's app in your folder |
-| 53-60 | 7. Create from a template | the six starters, one table, one run |
-| 60-75 | 8. An agent builds a feature | your app changed by the agent, still running |
-| 75-82 | 9. Upgrade | the app moved to the current framework |
-| 82-90 | 10. Publish it | your app as a registry starter |
-
-> **Checkpoint 15 minutes:** your app answers in a browser. Without that, read the "Stuck?" line of step 1.
-> **Checkpoint 45 minutes:** your app is open in a desktop window. Behind? Step 4 is the optional one; skip it and carry on.
-> **Checkpoint 75 minutes:** the agent's page is live. Still waiting? Give it five more minutes, then skip step 9.
-
-## 1. Create and run (5 minutes)
+| | macOS | Windows | Linux |
+| --- | --- | --- | --- |
+| Node.js 22.19 or newer (24 and 26 work) | `node -v` | `node -v` | `node -v` |
+| git | `git --version` | `git --version` | `git --version` |
+| one coding agent, logged in | `codex login status` or `claude --version` or `pi --version` | same | same |
+| GitHub account and `gh`, for the last block | `gh auth status` | same | same |
 
-```sh
-npm create acrylblends@latest my-hero blank
-cd my-hero
-npm install
-npm run dev
-```
+Install what is missing: Node from <https://nodejs.org> (the LTS), git from <https://git-scm.com>, the GitHub CLI from <https://cli.github.com> (`gh auth
+login` once), and one agent:
 
-You should see:
+- **Codex**: `npm i -g @openai/codex`, then `codex login`. If a run answers `model_not_found`, your account does not have the default model: pick one
+  your account supports (`/model` inside codex, or `model = "..."` in `~/.codex/config.toml`).
+- **Claude Code**: <https://claude.com/claude-code>, then run `claude` once to log in.
+- **pi with DeepSeek**: `npm i -g @earendil-works/pi-coding-agent`, and set your DeepSeek key in the terminal you will start the app from (the panel
+  starts pi from the app, so pi sees that terminal's environment). The preflight checks the key: `PASS agent pi (DeepSeek key found)`.
 
-```
-created my-hero (blank) in /Users/you/acryl-workshop/my-hero: … files, plugins instance, acryl-router, acryl-node-server, manifest, save
+  | macOS and Linux | Windows PowerShell | Windows cmd.exe |
+  | --- | --- | --- |
+  | `export DEEPSEEK_API_KEY=sk-...` | `$env:DEEPSEEK_API_KEY="sk-..."` | `set DEEPSEEK_API_KEY=sk-...` |
 
-Next:
-  cd my-hero
-  npm install
-  npm run dev
-```
+No prior knowledge of ACRYL, Cordis or Blends is needed; every new word is explained where it appears.
 
-then, from `npm run dev`:
+Make the workshop folder:
 
-```
-my-hero listening on http://127.0.0.1:3080 (data in /Users/you/acryl-workshop/my-hero/.acrylblends)
-```
+| macOS and Linux | Windows PowerShell | Windows cmd.exe |
+| --- | --- | --- |
+| `mkdir ~/acryl-workshop && cd ~/acryl-workshop` | `mkdir ~/acryl-workshop` then `cd ~/acryl-workshop` | `mkdir %USERPROFILE%\acryl-workshop` then `cd %USERPROFILE%\acryl-workshop` |
 
-Open that address: `{"app":"my-hero","ok":true}`. `/health` answers `{"ok":true}` too. Leave the terminal running.
+**On Windows.** Windows PowerShell 5.1 (the one Windows ships) has no `&&`: where this guide joins two commands with `&&`, type them as two lines, or join
+them with `;`. PowerShell 7 (`pwsh`) accepts `&&`. In cmd.exe, `Ctrl-C` asks `Terminate batch job (Y/N)?`: answer `Y`.
 
-**Stuck?** A busy port gets the next free one: use the address the app printed. The first `npm create` downloads the initializer, so give it a few
-seconds.
+**The agent setting that matters all day.** The app's agent is configured to act rather than to describe: when you ask for something, it writes the
+files, installs the plugin and clicks through the result itself. If your agent stops to ask "shall I proceed?", answer "do it now" and it continues; that
+one sentence is the difference between watching and building.
 
-## 2. Change one thing (7 minutes)
+## The path
 
-Open `src/routes.ts`. It builds an `Acryl` app and mounts it on the router. Add one line to that chain, just above `.get('/health', …)`, and keep the
-indentation of the lines around it:
+| Minutes | Block | What you get |
+| --- | --- | --- |
+| 0-10 | 0. Before you start, 1. The core in one breath | a checked machine, and an app with a route of your own, answering in a browser |
+| 10-40 | 2. The agent builds the interface | a board page with cards, a sidebar and live counts, written by the agent from inside |
+| 40-60 | 3. The agent drives the app | the agent opening the sidebar and ticking a card while you watch |
+| 60-75 | 4. The same app in a window | the app and its agent in a desktop window, driven there too, with its menu and settings |
+| 75-90 | 5. Deploy it, then publish it | the app running as a server, then listed in the registry |
 
-```ts
-      .get('/hello', (c) => c.json({ hello: 'workshop' }))
+> **Checkpoint 10 minutes:** your route answers in the browser.
+> **Checkpoint 40 minutes:** the agent's board is on screen.
+> **Checkpoint 60 minutes:** the agent has clicked through the page by itself.
+> **Checkpoint 75 minutes:** the same app is in a desktop window.
+
+## 1. The core in one breath (10 minutes)
+
+```sh
+npm create acrylblends@latest my-app agent
+cd my-app
+npm install
+npm run dev
 ```
 
-Save. The terminal prints `Change detected … Restarting 'src/main.ts'`, and `http://127.0.0.1:3080/hello` answers `{"hello":"workshop"}`. No restart
-command, no build step: the app watches its own source.
+Open the address it prints. You get a small app with a button in the corner, "Ask the agent": it opens the panel, the agent that will build and drive
+this app. It is the `agent` template.
 
-**Stuck?** No message means the file is not where the app watches; the message names the path it saw. A red error names the file and line.
+![The app's first page with the agent panel open on the right; the page follows the system theme, dark here](/docs-assets/workshop/s1-first-page.webp)
 
-## 3. Tests and the typecheck (8 minutes)
+The page follows your system's light or dark setting, so on a dark-mode machine it is dark as above. For the next two minutes forget the panel: an
+Acryl app is a function from a request to a response.
 
-Stop the server with `Ctrl-C`, then:
+Open `src/routes.ts` and add one line to the chain, just above `.get('/health', …)`, keeping the indentation of the lines around it:
 
-```sh
-npm test
-npm run check
+```ts
+      .get('/hello', (c) => c.json({ hello: 'workshop' }))
 ```
 
-`npm test` ends with `ℹ pass 5`, `ℹ fail 0`. `npm run check` prints nothing when the types are clean.
+Save: the terminal prints `Restarting 'src/main.ts'` (Node 24 and 26 print `Change detected …` on the line before it; Node 22 prints only the
+`Restarting` line), and `/hello` answers `{"hello":"workshop"}`. Stop the server (`Ctrl-C`; in cmd.exe answer `Y`), run `npm test` and `npm run check`:
+both pass (`npm test` reports 14 passing tests). That is the whole core: a route, a test, a typecheck.
 
-Now add a test for your route in `test/`: copy the style of the existing test file, request `/hello` and expect `{"hello":"workshop"}`. `npm test`
-again; a failure names the file and line.
+**Stuck?** A busy port means the app printed the next free one; use that address. `npm test` failing on your line names the file and the type.
 
-**Stuck?** `npm run check` complaining about your new line is the typechecker doing its job; the message says which type it expected.
+## 2. The agent builds the interface (30 minutes)
 
-## 4. Data: JSON, then SQLite (8 minutes, optional)
-
-An app keeps data through a **port**: a small interface a plugin provides. The smallest is `kv`, a JSON file in the app's own folder.
+Start the app (on pi, in the terminal where `DEEPSEEK_API_KEY` is set):
 
 ```sh
-npx acrylblends add acryl-kv-json
-npm install
+npm run dev
 ```
 
-`add` copies the plugin into `plugins/` and prints how to mount it. Three edits:
+Open the address it prints and click "Ask the agent". Ask it, in one message:
 
-1. `blend.yaml`, before `- id: server`: add the provider row (the row's id is yours to pick; the name is the plugin):
+> Do it now, without asking for approval. Build a board page at /board: three columns (backlog, doing, done) with cards that have a checkbox to mark
+> them done, a sidebar with filters (all, mine, done) and a count on each filter, a button that opens and closes the sidebar, and a header button
+> "New card" that adds one. Use the app's own state so the counts update live. Build it as a plugin in plugins/, install it into the running app, then
+> go to /board yourself and check it looks right, and tell me what you saw.
 
-   ```yaml
-       - id: kv
-         name: acryl-kv-json
-   ```
+What happens next is the workshop: the agent reads `AGENTS.md` and `docs/framework` (both are in your app), writes a Cordis plugin under `plugins/`,
+installs it into the running app as an extension (`.acryl/bin/acryl plugin add plugins/board`), and goes to `/board` through the door to look at what it
+built. The panel shows `Working... m:ss` while it runs; with pi the build took about six minutes. The panel is on every page of the app, so when the
+agent moves the page to `/board`, the panel comes along and keeps following the run.
 
-2. `src/app.ts`: import the plugin and register it under that name:
+![The panel while the agent builds: the request, then Working... 0:04 below it](/docs-assets/workshop/s2-panel-building.webp)
 
-   ```ts
-   import * as kvJson from '../plugins/acryl-kv-json/src/index.ts'
-   ```
+![The board the agent built: three columns with cards, and a sidebar with filters and counts](/docs-assets/workshop/s3-board.webp)
 
-   ```ts
-   export const registry = { 'acryl-router': router, 'acryl-node-server': nodeServer, 'acryl-kv-json': kvJson, routes }
-   ```
+Then make it yours: open the plugin it wrote, change a colour or a label, save, and watch the app reload. The code is in your folder and belongs to you;
+the agent wrote it, you own it. Every agent builds a slightly different board: yours may need a title typed before "New card" adds one, or keep the
+sidebar always open.
 
-3. `src/routes.ts`: declare the port and count visits in your route:
+**Stuck?** If the agent describes the plan and stops, tell it "do it now, without asking for approval". An app made with an older release gets the
+current panel and fixes with `npx acrylblends@latest upgrade`.
 
-   ```ts
-   import type {} from '../plugins/acryl-kv/src/cordis.ts'
-   ```
+## 3. The agent drives the app (20 minutes)
 
-   ```ts
-     inject: ['router', 'kv'],
-   ```
+The same agent, in the same panel, now uses the door: a channel into the running page with `look` (a snapshot of what is on screen, with refs) and
+`act` (click, type, select, press, scroll, wait, and `navigate` or `reload` the page).
 
-   ```ts
-     .get('/hello', async (c) => {
-       const visits = await ctx.kv.update('visits', (n) => (n ?? 0) + 1)
-       return c.json({ hello: 'workshop', visits })
-     })
-   ```
+Ask it:
 
-`npm run dev` again and open `/hello` twice: `visits` goes 1, 2. The file is `my-hero/.acrylblends/kv.json`.
+> Do it now, without asking for approval. On /board, use the door to open the sidebar, tick one card with its checkbox, set the filter to done, then
+> look again and tell me what the counts say.
 
-The relational port is `db`, with numbered SQL migrations:
+Watch the page: the card ticks, the filter changes, the counts move. While each action runs, a bar at the bottom of the page says `Agent is driving:
+clicking` (or looking, typing) with a Stop button; it shows only for that moment, so most of the time you see the page change and the panel's `Working...`
+line. The panel's own Stop button ends the whole run. Every action is a line in `.acryl/audit/` afterwards. With pi the drive was six door calls in
+under two minutes, most of it the model thinking.
 
-```sh
-npx acrylblends add acryl-db-sqlite
-mkdir migrations
-printf 'CREATE TABLE visits (id INTEGER PRIMARY KEY, at TEXT NOT NULL);\n' > migrations/001-visits.sql
-npm install
-```
+Then ask it to check its own work in the way a person would:
 
-A row in `blend.yaml` (`- id: db`, `name: acryl-db-sqlite`), then the migration folder in `src/app.ts`, where the app is composed: the path is set
-there, not in the manifest, because a relative path in the manifest has no folder to resolve against.
+> Do it now, without asking for approval. Click "New card" twice, look at the board, and tell me whether the counts agree.
 
-```ts
-import * as dbSqlite from '../plugins/acryl-db-sqlite/src/index.ts'
-// in the registry: 'acryl-db-sqlite': dbSqlite
-const projectRoot = fileURLToPath(new URL('..', import.meta.url))
-// in the compose options next to server:
-db: { migrations: join(projectRoot, 'migrations') },
-```
+If your board needs a title before "New card" adds a card, the agent says so, and the counts agree because nothing was added; ask it to type a title
+first if you want to see them move.
 
-Then `inject: ['router', 'kv', 'db']` with `import type {} from '../plugins/acryl-db/src/cordis.ts'`, and in the route
-`await ctx.db.run('INSERT INTO visits (at) VALUES (?)', new Date().toISOString())` before the reply. The database is `my-hero/.acrylblends/data.sqlite`,
-and the migrations run at start, in order.
+**Stuck?** If the agent says it cannot see a page, reload the app's tab: the page connects to the door when it loads.
 
-**Stuck?** `migrations "migrations" is relative, but this app has no file base URL` means the app has `acrylblends` older than 1.0.3, where a relative path in `blend.yaml` was not read
-from the app folder; move it into `src/app.ts` as above, or update (`npx acrylblends@latest upgrade`). "no such table" means the file is not in `migrations/` at the app root.
+## 4. The same app in a desktop window (15 minutes)
 
-## 5. A desktop window (7 minutes)
+**First close the browser tab of the app.** While a browser tab of the app is open, the agent's page actions can go to that tab instead of the
+window (the door picks a page when the agent does not name a window), and you would watch an unchanged window. Keep `npm run dev` running.
 
 ```sh
 npx acrylblends add desktop
@@ -193,189 +166,119 @@ npm install
 npm run desktop
 ```
 
-A window opens, showing the same routes and the same data. The app's own code never imports Electron; every Electron call lives in `plugins/desktop`,
-and the window's browser data stays inside `my-hero/.acrylblends/electron`. Close the window when you are done (`Cmd-Q`, `Alt-F4`).
-
-**Stuck?** The first `npm run desktop` downloads Electron (about 200 MB). No display (a bare server)? Skip this step; nothing later needs it.
+The first `npm run desktop` downloads Electron (about 200 MB), then the window attaches to the running server and says so:
 
-## 6. Pull a starter from the registry (8 minutes)
-
-The registry is where people publish starters: <https://acrylblends.github.io/blends> (the starters written for this framework say
-`runtime: acrylblends`; older ACRYL app starters are refused with a line saying so). Pull one by id, straight into a new folder:
-
-```sh
-cd ~/acryl-workshop
-npm create acrylblends@latest from-the-registry -- --from <starter-id>
-cd from-the-registry
-npm install
-npm run dev
+```text
+desktop: attached to the app already running from this folder at http://127.0.0.1:3288 (its server keeps running when the window closes)
+desktop: windows and menu are available to the door (acryl window list, acryl menu list)
 ```
 
-The same command takes a git repository or a folder: `--from github:you/starter` or `--from ../a-template`. You get a complete app someone else
-published, with its plugins, its dependencies and its `blend.yaml`, in your folder and yours to change. Nothing is installed for you: the starter's
-`Next:` block asks for the same `npm install` as step 1.
+A window opens on the same app, from the same server: your board, your sidebar, your panel. First drive the page in the window the way you did in block
+3: open the panel there and ask the agent to open the sidebar and change a filter. Look and act work the same way through the window.
 
-For the workshop's own registry, name it:
+![The agent driving the board inside the desktop window: the Done filter it just set, and the panel's Working... line](/docs-assets/workshop/s4-agent-drives-window.webp)
 
-```sh
-npm create acrylblends@latest from-the-workshop -- --from <id> --registry github:acryldev/workshop-2026-11-20
-```
+Then hand the agent the window itself, not only the page inside it. Ask:
 
-Starters for this workshop: `acrylblends.notes-desktop` (notes with a desktop window), `acrylblends.chat`, `acrylblends.agent`.
+> List the windows that are open, open a second one with the board in it, open the app's settings from the menu, and switch the appearance to dark.
 
-**Stuck?** The `--` before `--from` is npm's, not ours: without it npm swallows the flag. A refused id prints its reason first (`error: acryl.gtd is an
-ACRYL app starter: open it in the ACRYL app`) and then npm's own error block; read the first lines, not the last.
+The agent lists the windows, opens a second one, clicks the menu's Settings item, and changes the app's appearance on the settings page; each shows on
+screen as it happens. The Settings item is in the application menu on macOS (`my-app > Settings...`, `Cmd+,`) and the first item of the File menu on
+Windows and Linux (`Ctrl+,`); it opens `/settings` in a window of its own.
 
-## 7. Create from a template (7 minutes)
+The appearance is saved for the whole app. The app's own pages (`/`, `/settings`) use it; a window that is already open picks it up when it reloads, so
+ask the agent "reload window 1 and look at it" to see the change there. On a machine already in dark mode, dark looks like before: pick Light to see
+it change. A page the agent built (the board) follows the system theme unless you ask the agent to follow the app's appearance too.
 
-Every app begins from one of six templates, the same list in `npm create acrylblends` and `acrylblends init`:
+![Two desktop windows: window 1 on the app's page in the dark appearance, and the Settings window showing Saved: Dark](/docs-assets/workshop/s5-two-windows.webp)
 
-| Template | What you get |
-| --- | --- |
-| `blank` | the router, the server and one route: what you just built |
-| `nodejs` | a page rendered with JSX and a client component, without a bundler |
-| `notes` | a multi-user notes app on the `db` port: sign-up, sessions, migrations, search, a typed client |
-| `chat` | an answer streamed over server-sent events from an OpenAI-compatible API, history in SQLite |
-| `todo` | a to-do list on the router and live state |
-| `agent` | the blank app with an offline agent that writes and installs plugins into the running app |
+**Tip.** `navigate` answers with the status: a `404` means the app does not serve that path, and you can navigate straight back to one it does.
 
-Try the one with a database and accounts, in a window:
+Close the windows when you are done. The last window does not close through the door without `--force` (closing it ends the desktop app), so close it
+yourself or tell the agent it may.
 
-```sh
-cd ~/acryl-workshop
-npm create acrylblends@latest notes-app notes
-cd notes-app && npm install
-npx acrylblends add desktop && npm install && npm run desktop
-```
-
-Sign up, add a note, close the window; run `npm run dev` and the note is still there, because it lives in `notes-app/.acrylblends/data.sqlite`.
+**Stuck?** On Ubuntu 23.10+ the launch starts with `--no-sandbox` and says why; the AppArmor route is in
+`docs/framework/getting-started/desktop.md`. If the agent reports success but the window did not change, a browser tab of the app is still open: close
+it and ask again.
 
-**Stuck?** The sign-in page is at `/login`; the root redirects there. Delete the folder when you are done with it.
+## 5. Deploy it, then publish it (15 minutes)
 
-## 8. An agent builds a feature (15 minutes)
-
-The agent panel turns a coding agent you already use into a chat in the corner of the page. It needs the plugins the `agent` template ships (its model,
-tools and memory), so this step builds a second, small app from that template; it is the app you publish in step 10.
+**Deploy the app without its agent.** The agent, the panel and the terminal driver are development tools: with `NODE_ENV=production` they start
+nothing, while the app's own routes, plugins, state and database run as always. That is the app you put on a server. Stop `npm run dev` first.
 
 ```sh
-cd ~/acryl-workshop
-npm create acrylblends@latest agent-app agent
-cd agent-app
-npm install
-npx acrylblends add agent-panel driver-pty
-npx acrylblends add desktop
-npm install
-npm run dev
+NODE_ENV=production npm start
 ```
 
-`add agent-panel` adds the plugin rows the panel needs and registers it for you, and prints what it changed. (On a `blank` app it refuses and says
-which rows are missing: that is why this step uses the `agent` template.) Open the page, click the panel button in the corner, pick `codex` (or
-`claude`, or `pi` when pi has its DeepSeek login in your home folder), and ask:
+(The command is the app's own `start` script; on Windows, `set NODE_ENV=production&& npm start` in cmd, or `$env:NODE_ENV="production"; npm start` in
+PowerShell.) It prints `extensions (read-only): board`: the board the agent installed runs, and nothing can install or remove a plugin.
 
-> Add a page at /board that lists the app's tasks, newest first, and a test for it.
+That is the same app on any Node host: copy the folder (or clone the repository the app was saved to), run `npm install --omit=dev`, and start it with
+`NODE_ENV=production`. On its own the app listens on `127.0.0.1` at a port chosen from its folder; a server must say where to listen. The app reads
+`ACRYLBLENDS_HOST` and `ACRYLBLENDS_PORT` (not `PORT`):
 
-The agent reads `AGENTS.md`, reads `docs/framework` (which is in your app), edits your files, runs your tests, and the app reloads itself. It takes a
-few minutes; the panel shows each step, and has a stop button. Open `/board` when it is done.
-
-A terminal agent works too: choose `pty:codex` (or `pty:claude`, `pty:pi`) for its normal interactive session inside the app folder, where it can use
-the door (`.acryl/bin/acryl`) to look at the page it built.
-
-**Stuck?** The panel uses your own agent account: `codex login` (or `claude`) in a terminal first. Your own agent settings travel with it: skills or hooks of your own can make it stop and ask for approval instead of acting, so write the task as "do it now, without asking for approval", or start the agent from a clean configuration (a fresh `CODEX_HOME`, or no personal skills). If `npm install` warns that npm blocked
-`node-pty`'s install script, ignore it: prebuilt binaries ship. Only if the panel lists no `pty:` terminal, run `npm approve-scripts node-pty` and
-`npm rebuild node-pty` (the `add` output says the same).
+| macOS and Linux | Windows PowerShell | Windows cmd.exe |
+| --- | --- | --- |
+| `ACRYLBLENDS_HOST=0.0.0.0 ACRYLBLENDS_PORT=8080 NODE_ENV=production npm start` | `$env:ACRYLBLENDS_HOST="0.0.0.0"; $env:ACRYLBLENDS_PORT="8080"; $env:NODE_ENV="production"; npm start` | `set ACRYLBLENDS_HOST=0.0.0.0&& set ACRYLBLENDS_PORT=8080&& set NODE_ENV=production&& npm start` |
 
-## 9. Upgrade (7 minutes)
+Nothing in the app assumes ACRYL's own infrastructure: it is one Node process, one port, and its data in `.acrylblends/` next to it.
 
-Your app carries its framework plugins as source, so a new release moves them in place and leaves your code alone. Run the tool by its full name:
-**`npx acrylblends@latest`**, because an app's own copy of `acrylblends` shadows the bare command and an older copy has no `upgrade` at all.
+**Publish it as a starter.** Your app already is one: `blend.yaml` names it, `plugins/` holds its code.
 
 ```sh
-cd ~/acryl-workshop/my-hero
-npx acrylblends@latest upgrade --dry-run
-npx acrylblends@latest upgrade
-npm install && npm test
+cd ~/acryl-workshop
+gh repo fork acryldev/workshop-2026-11-20 --clone
+cd workshop-2026-11-20
+node scripts/make-entry.mjs ../my-app <your-github-login>.my-app --description "the board my agent built"
+git add blends && git commit -m "add <your-github-login>.my-app"
+git push
+gh pr create --fill --repo acryldev/workshop-2026-11-20
 ```
 
-The dry run lists what would be replaced; the real run replaces untouched files and stops with a diff if you edited one (move your change into a plugin
-of your own, or use `--force`, which backs the edited copies up first). An app made by this version is already current, so both commands answer
-`everything is up to date`: that is the mechanism working, and an app made by an earlier release lists what it would move. Your tests still pass
-afterwards.
-
-## 10. Publish it, and the hero moment (8 minutes)
-
-The app you publish is `agent-app`, the one the agent changed in step 8 (keep `my-hero` too: it is yours, saved the same way). It is already a
-**starter**: `blend.yaml` names it, lists its rows, and `plugins/` holds its code. Two parts make it public: your own copy, then the registry.
-
-**Your own copy first.** `npm run save` commits the app and pushes it to its remote (it refuses a file that looks like a secret, and refuses to push a
-private app to a public remote). Create an empty repository on your git host, set it as `origin`, run `npm run save`.
-
-**The registry.** Publishing is a pull request to the workshop registry, `github.com/acryldev/workshop-2026-11-20`, and it is four commands.
-
-1. Fork and clone it, then let its script build the entry from your app:
-
-   ```sh
-   cd ~/acryl-workshop
-   gh repo fork acryldev/workshop-2026-11-20 --clone
-   cd workshop-2026-11-20
-   node scripts/make-entry.mjs ../agent-app <your-github-login>.agent-app --description "the app I built in the workshop"
-   ```
+(On Windows PowerShell 5.1, `cd ~/acryl-workshop` works as written; in cmd.exe use `cd %USERPROFILE%\acryl-workshop`. Type the `git add` and `git
+commit` as two lines, or join them with `;`.)
 
-   `make-entry` copies the app into `blends/<your-github-login>.agent-app/` without `node_modules`, `.git` or the app's data, marks its `blend.yaml`
-   public and licensed under that id, and writes the `acryl.template.json` that makes it pullable. The entry is the whole app: its dependencies come with
-   it, so whoever pulls it gets the desktop shell without adding it again. The id is lowercase, `<login>.<name>` with letters, digits and dashes.
+A check runs on the pull request and merges it: your starter is listed in about two minutes, and anyone can start from it with
+`npm create acrylblends@latest another-app -- --from <your-github-login>.my-app --registry github:acryldev/workshop-2026-11-20`.
 
-2. Commit, push and open the pull request:
+![The workshop registry's page, listing the starters other people published](/docs-assets/workshop/s6-registry.webp)
 
-   ```sh
-   git add blends && git commit -m "add <your-github-login>.agent-app"
-   git push
-   gh pr create --fill --repo acryldev/workshop-2026-11-20
-   ```
+As an aside, for an app made before this release: `npx acrylblends@latest upgrade` moves the framework plugins it carries to the installed version,
+leaving your own code alone (an app you made today answers "everything is up to date").
 
-3. A check runs on the pull request, and when it passes the pull request is merged: your starter is listed, usually well under two minutes. If it
-   refuses, it comments what to change; fix, commit, push again and it re-checks. To take an app down, open a pull request that removes the folder:
-   `git rm -r blends/<your-github-login>.agent-app`.
+**Stuck?** The registry's check comments what to change; fix, commit, push again. `gh auth status` not logged in means `gh auth login`. A production app
+with no agent is correct: that is the design, not a missing piece.
 
-Anyone can then start from it, in the browser or in a window:
-
-```sh
-npm create acrylblends@latest my-app -- --from <your-github-login>.agent-app --registry github:acryldev/workshop-2026-11-20
-```
+## Browser only (WebBoxes.ai) TODO(M9)
 
-**Stuck?** The check's comment is the answer: read it, fix, push again. An id with a capital or a dot inside a part is refused by `make-entry`; use
-lowercase `<login>.<name>`. `gh: not found` means the GitHub CLI is not installed, and `gh auth status` saying not logged in means `gh auth login`.
+No local install? The same app, and the same agent building and driving it, will run as a hosted workspace: open it in a browser, pick a starter, and work
+in the same folders. Nothing to install, nothing to keep on your machine.
 
-> **The hero moment.** An app you created, with a page an agent wrote for it, running as a desktop window, saved in your own repository, and published
-> as a starter in the registry so the next person can pull it with one command. Along the way you built a second app from blank, a route, a test, a JSON
-> store and a SQLite database. Note what you did not write: the router, the server, the JSON file, the SQLite migrations, the window, the page.
+The hosted workspace is milestone M9; until it is live this section is a stub. When it is, it says the address, the sign-in it needs, and the two or three
+clicks that replace block 1 here - and the one-click WebBoxes.ai deploy of an app from block 5, which is the same app on their infrastructure instead of
+yours.
 
 ## Where next
 
-- **Read the docs you already have**: every app carries `docs/framework`, the same pages as <https://acrylblends.github.io/docs>. Start with
-  `cordis/acryl-in-a-cordis-app.md`, then `guides/data.md`, then `guides/production.md` (what runs in production, and what does not).
-- **Swap a provider by editing one row**: SQLite to Postgres (`npx acrylblends add acryl-db-postgres`), the browser to a window (`desktop`), one agent
-  to another (the panel's driver list).
-- **Teach your agent**: `AGENTS.md` in your app is what it reads first; add your team's conventions there and the next run follows them.
+- **Read the docs you already have**: every app carries `docs/framework`, the same pages as <https://acrylblends.github.io/docs>. The door's verbs are in
+  `agent/`, the data ports in `guides/data.md`, and `guides/production.md` says exactly what runs on a server.
+- **Teach the agent your app**: `AGENTS.md` is what it reads first; add your team's conventions there and it follows them in the next run.
+- **Swap a provider by editing one row**: SQLite to Postgres, the browser to a window, one agent to another in the panel's driver list.
 - **Bring your own tool**: <https://acrylblends.github.io/docs/guides/bring-your-own-tool> wraps an outside library as a provider of a port.
 
-## Browser only (WebBoxes.ai) TODO(M9)
-
-No local install? The same app, and the same agent, will run as a hosted workspace: open it in a browser, pick a starter, and work in the same three
-folders. Nothing to install, nothing to keep on your machine.
-
-The hosted workspace is milestone M9 and is due before the workshop, so this section is a stub until it is live: write the address, the sign-in it
-needs, and the two or three clicks that replace steps 1-2 here, then let the local steps stand for anyone who wants the app on their own disk.
-
 ---
 
 ## If something goes wrong
 
 | Symptom | Do |
 | --- | --- |
+| The preflight prints `FIX` lines | run each one, then `npx acrylblends@latest preflight` again |
 | `npm create` fails or hangs | check the network; the facilitator has prepared apps |
 | A port is taken | use the address the app printed |
-| The agent cannot log in | `codex login` / `claude` in a terminal, then retry in the panel |
-| You want to start over | delete your app folder and repeat step 1; nothing lives outside it |
+| The agent cannot log in | `codex login` / `claude` / `pi` in a terminal, then retry in the panel |
+| Codex answers `model_not_found` | pick a model your account supports: `/model` in codex, or `model = "..."` in `~/.codex/config.toml` |
+| pi does not start or has no key | set `DEEPSEEK_API_KEY` in the terminal that runs `npm run dev`, restart it, and run the preflight |
+| The agent plans and stops | reply "do it now"; the config asks it to act, but a model sometimes waits |
+| `&&` is an error in PowerShell | Windows PowerShell 5.1: type the two commands as two lines, or join them with `;` |
+| The agent says it acted, but the desktop window did not change | close the app's browser tab, then ask again |
 | Anything else | the **Stuck?** line of the step, then your facilitator |
-
-Behind at a checkpoint? Skip step 4 (data) first, then the second app in step 7. Steps 1-3, 5, 8-10 are the spine.