acrylblends 1.0.10 → 1.2.0

package/docs/framework/workshop/README.md

@@ -1,381 +1,270 @@
-# From nothing to your own app: the ACRYL Blends workshop
+# Build your app inside the ACRYL frame: 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 that opens in ACRYL's own IDE: projects on the left, your app's page in the middle, files,
+changes, checks and terminals on the right, a chat model that works on your app beside it, and Claude, Codex or Pi running in terminal tabs in
+the same folder. **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, opened by the frame.
 
-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.
+The frame is the workshop's point. You do not edit a folder and alt-tab to a browser: your app is a page inside the workspace, the agents work in
+the same folder the frame shows, and every change you or an agent makes is one restart away from the page.
 
-## What you need (10 minutes)
+This guide is for **acrylblends 1.2.0 or newer**; `npm create acrylblends@latest` gives you that. An app you made with an older release gets the
+frame with the upgrade in block 6.
 
-| | 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:
-
-```sh
-mkdir ~/acryl-workshop && cd ~/acryl-workshop
-```
-
-## The path
-
-| 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)
+Run this first. It checks everything below and prints one line per check, with the exact command for anything missing:
 
 ```sh
-npm create acrylblends@latest my-hero blank
-cd my-hero
-npm install
-npm run dev
-```
-
-You should see:
-
-```
-created my-hero (blank) in /Users/you/acryl-workshop/my-hero: … files, plugins instance, acryl-router, acryl-node-server, manifest, save
-
-Next:
-  cd my-hero
-  npm install
-  npm run dev
-```
-
-then, from `npm run dev`:
-
+npx acrylblends@latest preflight
 ```
-my-hero listening on http://127.0.0.1:3080 (data in /Users/you/acryl-workshop/my-hero/.acrylblends)
-```
-
-Open that address: `{"app":"my-hero","ok":true}`. `/health` answers `{"ok":true}` too. Leave the terminal running.
 
-**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.
+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.
 
-## 2. Change one thing (7 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 |
 
-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:
+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:
 
-```ts
-      .get('/hello', (c) => c.json({ hello: 'workshop' }))
-```
+- **Claude Code**: <https://claude.com/claude-code>, then run `claude` once to log in.
+- **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`).
+- **pi with DeepSeek**: `npm i -g @earendil-works/pi-coding-agent`, and set your DeepSeek key in the terminal you start the app from (the terminal
+  tabs inherit that environment). The preflight checks the key: `PASS agent pi (DeepSeek key found)`.
 
-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.
+| macOS and Linux | Windows PowerShell | Windows cmd.exe |
+| --- | --- | --- |
+| `export DEEPSEEK_API_KEY=sk-...` | `$env:DEEPSEEK_API_KEY="sk-..."` | `set DEEPSEEK_API_KEY=sk-...` |
 
-**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.
+**One model key for the chat.** The frame's chat needs a model: a DeepSeek API key from <https://platform.deepseek.com> is the shortest path (you add
+it in block 3). A Claude or ChatGPT subscription works too, through **Sign in with an account** on the same Settings page.
 
-## 3. Tests and the typecheck (8 minutes)
+No prior knowledge of ACRYL, Cordis or Blends is needed; every new word is explained where it appears.
 
-Stop the server with `Ctrl-C`, then:
+Make the workshop folder:
 
-```sh
-npm test
-npm run check
-```
-
-`npm test` ends with `ℹ pass 5`, `ℹ fail 0`. `npm run check` prints nothing when the types are clean.
+| 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` |
 
-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.
+**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?** `npm run check` complaining about your new line is the typechecker doing its job; the message says which type it expected.
+**The agent setting that matters all day.** The agents are configured to act rather than to describe: when you ask for something, they write the
+files and check the result. 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.
 
-## 4. Data: JSON, then SQLite (8 minutes, optional)
+## The path
 
-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.
+| Minutes | Block | What you get |
+| --- | --- | --- |
+| 0-10 | 0. Before you start | a checked machine, one model key, a folder |
+| 10-20 | 1. Create the app, open the frame | the app running and shown inside the ACRYL frame |
+| 20-25 | 2. Your first change | the app's page in the frame showing your edit |
+| 25-30 | 3. Connect your model in Settings > Models | a chat that answers |
+| 30-50 | 4. Chat: your model builds a page | a board page the model wrote and you saw at /app/board |
+| 50-65 | 5. A coding agent in a terminal tab | Claude, Codex or Pi working in the app's folder |
+| 65-80 | 6. Upgrade an older app onto the frame | an app from before today, opened by the frame |
+| 80-90 | 7. Publish it as a starter | the app listed in the workshop registry |
+
+> **Checkpoint 20 minutes:** the app's page is in the frame.
+> **Checkpoint 30 minutes:** the chat answers.
+> **Checkpoint 50 minutes:** the model's board is at /app/board.
+> **Checkpoint 65 minutes:** an agent in a terminal has changed the app.
+
+## 1. Create the app; the frame opens on it (10 minutes)
 
 ```sh
-npx acrylblends add acryl-kv-json
+npm create acrylblends@latest my-app agent
+cd my-app
 npm install
+npm run dev
 ```
 
-`add` copies the plugin into `plugins/` and prints how to mount it. Three edits:
+`npm install` is bigger than a framework-only app: it brings the frame and the chat engine (about 500 MB together, much less on a warm package
+cache). `npm run dev` starts the app inside the frame and prints one line:
 
-1. `blend.yaml`, before `- id: server`: add the provider row (the row's id is yours to pick; the name is the plugin):
-
-   ```yaml
-       - id: kv
-         name: acryl-kv-json
-   ```
+```text
+acrylblends host: http://127.0.0.1:3489/?token=...
+```
 
-2. `src/app.ts`: import the plugin and register it under that name:
+Open that address (it is a free port on your machine; never a fixed one). It stays the same every time you start the app, and it is the way back in
+later: `npx acrylblends open` prints it again while the frame is running. The first time, DeepSeek Harness shows a **Preview Notice**: press **Continue**. Then the frame opens **on your app**: the page in the middle is `my-app`'s own page, in a tab named after the app.
 
-   ```ts
-   import * as kvJson from '../plugins/acryl-kv-json/src/index.ts'
-   ```
+![The frame on first run: projects on the left with the app selected, the app's page in the canvas, the tab strip with the app's tab](/docs-assets/workshop/s1-frame.webp)
 
-   ```ts
-   export const registry = { 'acryl-router': router, 'acryl-node-server': nodeServer, 'acryl-kv-json': kvJson, routes }
-   ```
+The three columns are ACRYL's IDE:
 
-3. `src/routes.ts`: declare the port and count visits in your route:
+- **Left:** your workspaces and projects. `my-app` is selected; the account row above and **Settings** below.
+- **Middle:** tabs. `my-app` is your app's page; the `+` at the left of the tab strip opens more (terminal, browser, files, chat, agents).
+- **Right:** open it with the panel button at the top right (or `Cmd/Ctrl+B`): **Files**, **Changes**, **Review**, **Checks**, **Comments** and a
+  terminal. The bottom bar is the terminal dock.
 
-   ```ts
-   import type {} from '../plugins/acryl-kv/src/cordis.ts'
-   ```
+The app's page also has an agent of its own: **Ask the agent** at the bottom right opens the app's panel (the offline agent unless the app is given
+a model). The frame's chat in the next blocks is the tool you will use; the panel is there for the app to ship with.
 
-   ```ts
-     inject: ['router', 'kv'],
-   ```
+**Stuck?** A busy port means the terminal printed a different address; use that. `npm install` failing on the native terminal package needs a C++
+toolchain: on macOS `xcode-select --install`, on Windows the "Desktop development with C++" workload of Visual Studio Build Tools, on Ubuntu
+`sudo apt install build-essential python3`.
 
-   ```ts
-     .get('/hello', async (c) => {
-       const visits = await ctx.kv.update('visits', (n) => (n ?? 0) + 1)
-       return c.json({ hello: 'workshop', visits })
-     })
-   ```
+## 2. Your first change, seen at /app (5 minutes)
 
-`npm run dev` again and open `/hello` twice: `visits` goes 1, 2. The file is `my-hero/.acrylblends/kv.json`.
+Open the right panel (**Files**), expand `src`, click `routes.ts`. Find the sentence the page shows ("This app runs an agent unless it is switched
+off...") and change it to something that is yours. Press **Save** in the editor's bar (or `Cmd/Ctrl+S`).
 
-The relational port is `db`, with numbered SQL migrations:
+The running app does not pick a source change up by itself. Stop the host with `Ctrl-C` in the terminal where `npm run dev` runs (in cmd.exe answer
+`Y`), then start it again:
 
 ```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
+npm run dev
 ```
 
-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.
+The frame reconnects on its own, on the same address (the port is stable per app), in a few seconds. If a chat tab opened in front, press the
+`my-app` tab: the page shows your sentence. That is the whole development loop for the rest of the day: edit, restart, look.
 
-```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') },
+```sh
+npm test
+npm run check
 ```
 
-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.
+Both pass: the app is TypeScript, with tests and a type check, and the scaffold made the folder a git repository, so **Changes** shows what you
+edited.
 
-**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.
+**Stuck?** If the page looks unchanged, the host did not restart (the terminal says `Restarting` or it is waiting on `Ctrl-C`). If the frame still
+says `Reconnecting...` after ten seconds, reload the tab: the address is the same one it was opened with. If the tab was closed, `npx acrylblends open`
+in the app's folder prints the address again.
 
-## 5. A desktop window (7 minutes)
+## 3. Connect your model: Settings > Models (5 minutes)
 
-```sh
-npx acrylblends add desktop
-npm install
-npm run desktop
-```
+Press **Settings** at the bottom of the left column, then **Models** in its sidebar. The page lists DeepSeek as a provider: paste your API key into
+**API key** and press **Apply**. It answers `Saved DeepSeek (deepseek-official).`; the key goes to the frame's own credentials store, never into the
+app folder.
 
-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`).
+![Settings > Models with the DeepSeek key field](/docs-assets/workshop/s2-settings-models.webp)
 
-**Stuck?** The first `npm run desktop` downloads Electron (about 200 MB). No display (a bare server)? Skip this step; nothing later needs it.
+Then reload the frame (`Cmd/Ctrl+R`): the page you already had open picks the key up on its next load. A Claude or ChatGPT subscription instead of a
+key: **Sign in with an account** on the same page.
 
-## 6. Pull a starter from the registry (8 minutes)
+If the frame greets you with DeepSeek Harness's **Add an API key to get started** card first, you can paste the key there and press **Save and
+continue**, or press **Configure later** and use Settings > Models; both write the same store.
 
-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:
+**Stuck?** "Loading the provider directory failed" means the host is not answering; start `npm run dev` again. A key that stays red is usually an
+extra space: paste it again.
 
-```sh
-cd ~/acryl-workshop
-npm create acrylblends@latest from-the-registry -- --from <starter-id>
-cd from-the-registry
-npm install
-npm run dev
-```
+## 4. Chat: your model works on the app (20 minutes)
 
-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.
+Press `+` at the left of the tab strip and choose **AcrylDSH Chat**; on the `my-app` row in the left pane, **New chat on my-app** does the same and
+binds the chat to the app's folder (the chat's workspace selector says `my-app`). Then ask, in one message:
 
-For the workshop's own registry, name it:
+> Do it now, without asking for approval. Build a board page at /board in this app: 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. Read AGENTS.md and the app's docs first. When you are
+> done, tell me what you changed.
 
-```sh
-npm create acrylblends@latest from-the-workshop -- --from <id> --registry github:acryldev/workshop-2026-11-20
-```
+The chat writes into `my-app` (watch the **Changes** panel fill), and the app's page at `/app` shows it after the loop from block 2: `Ctrl-C`, `npm
+run dev`, the frame reconnects. The board is at `/app/board`: type the address in the app tab's bar (the same address with `/board` at the end) and
+press **Go**.
 
-Starters for this workshop: `acrylblends.notes-desktop` (notes with a desktop window), `acrylblends.chat`, `acrylblends.agent`.
+![The AcrylDSH Chat tab with the request, beside the app](/docs-assets/workshop/s3-chat.webp)
 
-**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.
+Every model builds a slightly different board: yours may need a title typed before "New card" adds one, or keep the sidebar always open.
 
-## 7. Create from a template (7 minutes)
+**Stuck?** If the chat asks for a model, block 3 did not finish (or the page was not reloaded after Apply). If the model describes the plan and
+stops, reply "do it now, without asking for approval".
 
-Every app begins from one of six templates, the same list in `npm create acrylblends` and `acrylblends init`:
+## 5. A coding agent in a terminal tab (15 minutes)
 
-| 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 |
+Press `+` and choose **Claude**, **Codex** or **Pi** (or **New Terminal** and type the command yourself). The tab starts the agent in the app's
+folder: the terminal's prompt is `my-app`, and `pwd` prints the folder. Ask it, in the terminal:
 
-Try the one with a database and accounts, in a window:
+> Do it now, without asking for approval. Add a GET /time route that returns the current time as JSON, and a line on the app's page that shows it.
+> Then check it at http://127.0.0.1:3489/app/time.
 
-```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
-```
+The port in that address is the one the frame printed. The agent edits the files, and the same loop shows them: `Ctrl-C`, `npm run dev`, the frame
+reconnects, the `my-app` tab.
 
-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`.
+An agent that works in this folder can also use the app's **door**, the page channel the app carries in development: `.acryl/bin/acryl look` prints
+what is on the page with refs, and `act` clicks, types, selects, presses, scrolls, waits, navigates and reloads. Ask the terminal agent to look at
+the page before it tells you it is done; the app's own docs (`AGENTS.md`, `plugins/acryl-door`) say how.
 
-**Stuck?** The sign-in page is at `/login`; the root redirects there. Delete the folder when you are done with it.
+**Stuck?** An agent that says the terminal is not a TTY needs the tab, not a script. If the agent cannot log in, sign in in a terminal first
+(`claude`, `codex login`, pi with `DEEPSEEK_API_KEY`), then open the tab again.
 
-## 8. An agent builds a feature (15 minutes)
+## 6. Upgrade an older app onto the frame (10 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.
+An app made with an older acrylblends runs the framework only. The current release moves it onto the frame-hosted layout: the generated launcher,
+the frame's row and the app's plugins beside it, the mount config. **Your source stays yours**: the upgrade only touches the files acrylblends
+generated, plus the library plugins the app carries.
 
 ```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
+cd old-app
+npx acrylblends@latest upgrade
 npm install
 npm run dev
 ```
 
-`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:
-
-> Add a page at /board that lists the app's tasks, newest first, and a test for it.
-
-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.
+The report names every file it changed and ends with a `frame` line (for an app that already has the frame: `everything is up to date`). An app made
+today answers "everything is up to date" too. An app from a release **before 0.7.8** cannot start at all (its `src/main.ts` imports a `plugins/`
+folder that release did not write); the upgrade says so instead of touching it.
 
-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?** "is not the previous release's scaffold" means you edited a generated file: run with `--diff` to see it, save your version aside, and
+run again (or `--force`; the app's versions are backed up under `.acrylblends/upgrade-backup/`).
 
-**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).
+## 7. Publish it as a starter (10 minutes, take-home)
 
-## 9. Upgrade (7 minutes)
-
-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.
+Your app already is a starter: `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"
-   ```
-
-   `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.
-
-2. Commit, push and open the pull request:
+(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 `;`.)
 
-   ```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
-   ```
+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`.
 
-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`.
 
-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
-```
-
-**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`.
+## Browser only (WebBoxes.ai) TODO(M9)
 
-> **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.
+No local install? The same app, and the same agents working on 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. Until it is live this section is a stub.
 
 ## 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>.
+- **Teach the agents your app**: `AGENTS.md` is what they read first; add your team's conventions there and they follow 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 frame's agent 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 |
+| `npm install` fails building node-pty | install the C++ toolchain (block 1's **Stuck?**) and run it again |
 | 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 frame says `Reconnecting...` | wait ten seconds; then `npx acrylblends open` and open the address it prints |
+| Settings > Models shows no provider | the host is not running: `Ctrl-C`, `npm run dev` |
+| The chat asks for a model | finish block 3, then reload the page |
+| The model plans and stops | reply "do it now, without asking for approval" |
+| An agent cannot log in | `codex login` / `claude` / pi with `DEEPSEEK_API_KEY`, then open the tab again |
+| The app's page is unchanged after an edit | the host did not restart: `Ctrl-C`, `npm run dev` |
+| `&&` is an error in PowerShell | Windows PowerShell 5.1: type the two commands as two lines, or join them with `;` |
 | 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.