acrylblends 1.1.0 → 1.3.0

package/docs/framework/agents/index.md

@@ -7,7 +7,7 @@ A coding agent (Claude Code, Codex, OpenCode, Copilot and others) builds on Acry
 - `AGENTS.md`: where the API is, how a feature is built (an `Acryl` app mounted with `ctx.router.route`, a plugin registered in `src/app.ts` and `blend.yaml`, a state cell),
   the defaults and how each is swapped, the things that surprise people, and what must pass before a task is done (`npm test` and `npm run check`).
 - `CLAUDE.md`: the same text as `AGENTS.md`, so tools that read either file read the same guide.
-- One skill, `app-guide`, in `.claude/skills/app-guide/SKILL.md` and `.agents/skills/app-guide/SKILL.md` (the same text): where to read first, the one plugin folder, the defaults, the door, and what "done" means.
+- Two skills, `acryl-app` and `cordis-plugin`, in `.claude/skills/<name>/SKILL.md` and `.agents/skills/<name>/SKILL.md` (the same text in both places): how the app is put together and how to change and check it through the door, and how to add a feature as a Cordis plugin.
 - `.gitignore` lists `.acryl/`, the folder the door keeps its secret and state in, so `git add -A` stages none of it.
 
 ## One plugin folder

package/docs/framework/getting-started/desktop.md

@@ -1,6 +1,7 @@
 # Desktop
 
-An Acryl app also runs as a desktop app: an Electron window opens on the app's own server. It is the same app and the same code as `npm run dev`; nothing in the app changes. This page covers a plain Acryl app (the `nodejs`
+An Acryl app also runs as a desktop app: an Electron window opens on the app's own server. It is the same app and the same code as `npm run dev`; nothing in the app changes. A Blend app that runs inside the ACRYL frame
+(it has `scripts/ide-host.mjs`) gets the whole frame in the window, the same one `npm run dev` serves to the browser: see [The frame in the window](#the-frame-in-the-window). This page covers a plain Acryl app (the `nodejs`
 template) and a Blend app (the `agent` template or any other `acrylblends init` template). It runs from source today: packaging a distributable app (dmg, exe, deb) is not part of it yet.
 
 ## Add it
@@ -26,10 +27,28 @@ In a Blend app, the same two commands (`npx acrylblends add desktop`, `npm insta
 
 ## What `npm run desktop` does
 
-1. Serves the app on `127.0.0.1` with a free port: for a plain app, `app.fetch` from `src/app.ts` (`export default app`) through `acrylblends/node-server`; for a Blend app, its own `createApp`.
+1. For a frame app, attaches to the running frame or starts its host (see [The frame in the window](#the-frame-in-the-window)). Otherwise it serves the app on `127.0.0.1` with a free port: for a plain app, `app.fetch` from `src/app.ts` (`export default app`) through `acrylblends/node-server`; for a Blend app, its own `createApp`.
 2. Takes a single-instance lock: a second launch of the same app focuses the first window and exits.
-3. Opens one window on the server's address, with a locked-down renderer (context isolation, no Node in the page, the sandbox, web security). Navigation stays on the app's own origin; any other link opens in the system browser.
-4. When the window closes (or on SIGINT or SIGTERM), stops the server and exits.
+3. Opens one window on the server's address, with a locked-down renderer (context isolation, no Node in the page, the sandbox, web security). Navigation stays on the app's own origin; a link to any other `http(s)` or `mailto` address opens in the system browser.
+4. When the window closes (or on SIGINT or SIGTERM), stops the server or frame host it started (never one it attached to) and exits.
+
+## The frame in the window
+
+A Blend app made with the frame (`npm run dev` runs `scripts/ide-host.mjs`) opens the ACRYL frame in its desktop window, not only its page: the left panel with the
+projects and sessions, the right panel with Files, Changes and Review, Settings, terminal tabs, the DSH chat, and the app's own page in a browser tile. It is the
+same frame the browser shows; the desktop builds nothing of its own.
+
+1. When the frame already runs for this folder (`npm run dev` in another terminal), the window attaches to it: it reads the address the host keeps in
+   `.acrylblends/frame-url.json` (owner-only, with the launch token) and opens it. Closing the window leaves that host running.
+2. Otherwise the window starts the host itself, exactly as `npm run dev` does (the same npm and Node that ran `npm run desktop`; the host never runs inside
+   Electron), and opens the address it prints. Closing the window stops that host and everything it started, including its terminals, so its port is free
+   again. Ctrl-C in the terminal does the same: Electron runs in a process group of its own, and `npm run desktop` passes it exactly one signal (a second
+   one would end Electron before it could stop the host).
+3. Navigation follows ACRYL Desktop's rule: the frame's own address stays in the window, and its tiles (the app's page in an iframe) load freely. A link to any
+   other `http(s)` or `mailto` address opens in the system browser, and nothing else opens at all.
+4. The door's `window list` shows each window's address without the launch token.
+
+The application menu's `Settings...` (`Cmd+,` on macOS, in the app menu; `Ctrl+,` and the File menu on Windows and Linux) opens the frame's own Settings, the dialog the left panel's Settings button opens. `acrylblends.desktopPath` does not apply to a frame app, because the frame opens the app's page in its tile on first run.
 
 ## The first launch downloads Electron
 

package/docs/framework/guides/create-acrylblends.md

@@ -16,7 +16,7 @@
 
 Every template is a Cordis app: `blend.yaml` lists the plugins that are mounted, every plugin is a folder in `plugins/`, and the app is started by `src/main.ts`. A bare template name after the directory is the same as `--template`: `npm create acrylblends@latest my-app notes`. `bun` is no longer a template; the framework still runs on Bun (see [Bun](../getting-started/bun.md)), but a new app is a Cordis app on Node.
 
-Every template includes `AGENTS.md` and `CLAUDE.md` (the same text), one skill (`app-guide`) in `.claude/skills/` and `.agents/skills/`, and a copy of these docs in `docs/framework/`, so a coding agent working in the folder reads the
+Every template includes `AGENTS.md` and `CLAUDE.md` (the same text), two skills (`acryl-app`, `cordis-plugin`) in `.claude/skills/` and `.agents/skills/`, and a copy of these docs in `docs/framework/`, so a coding agent working in the folder reads the
 API from the folder.
 
 ## Passing arguments
@@ -55,7 +55,7 @@ bun create acrylblends@latest my-app --template nodejs
 | `[source]` | A template from outside the package: `github:owner/repo[#ref]`, `@scope/name[@version]` or a packed `.tgz` file. See [Templates from a repository or a package](#templates-from-a-repository-or-a-package). | `github:acme/starter` |
 | `--template <template>` | One of `blank`, `nodejs`, `notes`, `chat`, `todo`, `agent` (the same list as `acrylblends init --template`; `acryl-app` is accepted as `agent`). Skips the template question; a bare name after the directory means the same. | `--template notes` |
 | `--from <id \| source>` | A starter from the registry by its id (`acrylblends.notes-desktop`), or any source above. Only starters that declare `runtime: acrylblends` are made; an ACRYL app starter is refused. See [Starters from the registry](#starters-from-the-registry). | `-- --from acrylblends.notes-desktop` |
-| `--registry <source>` | Read the ids from this registry instead of the public one: `github:owner/repo` or a folder, with an `index.json` (at its root or in `registry/`). | `-- --from login.thing --registry github:acryldev/workshop-2026-11-20` |
+| `--registry <source>` | Read the ids from this registry instead of the public one: `github:owner/repo`, an `https://` address, or a folder, with an `index.json` (at its root or in `registry/`). | `-- --from login.thing --registry github:acryldev/workshop-2026-11-20` |
 | `--install` | Install the dependencies with the package manager after creating the project. For a template from a source, the install scripts it will run are listed first. | `--install` |
 | `--pm <packageManager>` | The package manager for `--install`: `npm`, `pnpm`, `yarn` or `bun`. Defaults to the one that started the initializer. | `--pm pnpm` |
 | `--yes`, `-y` | Ask nothing: use `nodejs` unless `--template` is given, and the directory `acryl-app`. | `-y` |
@@ -78,7 +78,9 @@ npm run dev
 - A starter with `runtime: acrylblends` is an `acrylblends` app: this command downloads its folder, gives the manifest to the new app (`metadata.id: acrylblends.my-notes`, `visibility: private`; the starter's id and licence stay the starter's), checks it for anything that looks like a secret, and writes it. Nothing in it is installed or run: `npm install` is yours to run, and the dependencies of the starter (a desktop starter brings `electron`) are in its `package.json`.
 - A starter for the ACRYL app (`runtime: acryl`, the older `acryl.*` entries) is refused with one line that says so, because its plugins run only inside the ACRYL app. Nothing is written.
 - An unknown id lists the starters this command can make.
-- The ids come from `https://acrylblends.github.io/registry/index.json`. `--registry github:owner/repo` reads another registry with the same layout (`index.json` and `blends/<id>/`), a team's own or a workshop's; `--registry ./folder` reads one on disk.
+- The ids come from `https://acrylblends.github.io/registry/index.json`, and only the starter you asked for is downloaded, as one archive checked against the integrity in the index; an archive that does not match is refused. When the site cannot give the starter, the registry's repository is read instead. `--registry github:owner/repo` reads another registry with the same layout (`index.json` and `blends/<id>/`), a team's own or a workshop's; `--registry ./folder` reads one on disk.
+
+A registry on any static host works with `--registry https://...`, if its `index.json` names an `archive` and an `integrity` for each entry: `workshop-registry/scripts/registry-archives.mjs` in this repository writes both when you deploy, on the copy you publish.
 
 To publish a starter of your own, see [the registry README](https://github.com/acrylblends/acrylblends.github.io/tree/main/registry): the folder of your app under `blends/<id>/` with an `acryl.template.json`, in a pull request.
 

package/docs/framework/workshop/README.md

@@ -1,14 +1,15 @@
-# An app that builds and drives itself: the ACRYL Blends workshop
+# Build your app inside the ACRYL frame: the ACRYL Blends workshop
 
-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.
+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.
 
-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.
+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.
 
-This guide is for **acrylblends 1.0.10 or newer**; `npm create acrylblends@latest` gives you that.
+This guide is for **acrylblends 1.3.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.
 
 ## 0. Before you start (10 minutes)
 
@@ -19,7 +20,7 @@ npx acrylblends@latest preflight
 ```
 
 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).
+first blocks do without.
 
 | | macOS | Windows | Linux |
 | --- | --- | --- | --- |
@@ -31,15 +32,18 @@ first blocks do without (`gh` is only needed in block 5).
 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:
 
+- **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`).
-- **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)`.
+- **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)`.
+
+| macOS and Linux | Windows PowerShell | Windows cmd.exe |
+| --- | --- | --- |
+| `export DEEPSEEK_API_KEY=sk-...` | `$env:DEEPSEEK_API_KEY="sk-..."` | `set DEEPSEEK_API_KEY=sk-...` |
 
-  | macOS and Linux | Windows PowerShell | Windows cmd.exe |
-  | --- | --- | --- |
-  | `export DEEPSEEK_API_KEY=sk-...` | `$env:DEEPSEEK_API_KEY="sk-..."` | `set DEEPSEEK_API_KEY=sk-...` |
+**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.
 
 No prior knowledge of ACRYL, Cordis or Blends is needed; every new word is explained where it appears.
 
@@ -52,178 +56,169 @@ Make the workshop folder:
 **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`.
 
-**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.
+**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.
 
 ## The path
 
 | 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 |
-
-> **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)
+| 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
-npm create acrylblends@latest my-app agent
+npm create acrylblends@latest my-app agent -- --desktop
 cd my-app
 npm install
 npm run dev
 ```
 
-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.
-
-![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)
-
-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.
+`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:
 
-Open `src/routes.ts` and add one line to the chain, just above `.get('/health', …)`, keeping the indentation of the lines around it:
-
-```ts
-      .get('/hello', (c) => c.json({ hello: 'workshop' }))
+```text
+acrylblends host: http://127.0.0.1:3489/?token=...
 ```
 
-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.
+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.
 
-**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.
+![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)
 
-## 2. The agent builds the interface (30 minutes)
+The three columns are ACRYL's IDE:
 
-Start the app (on pi, in the terminal where `DEEPSEEK_API_KEY` is set):
+- **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.
 
-```sh
-npm run dev
-```
+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.
 
-Open the address it prints and click "Ask the agent". Ask it, in one message:
+**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`.
 
-> 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.
+## 2. Your first change, seen at /app (5 minutes)
 
-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.
+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 panel while the agent builds: the request, then Working... 0:04 below it](/docs-assets/workshop/s2-panel-building.webp)
+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:
 
-![The board the agent built: three columns with cards, and a sidebar with filters and counts](/docs-assets/workshop/s3-board.webp)
-
-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.
-
-**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`.
-
-## 3. The agent drives the app (20 minutes)
+```sh
+npm run dev
+```
 
-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).
+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.
 
-Ask it:
+```sh
+npm test
+npm run check
+```
 
-> 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.
+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.
 
-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.
+**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.
 
-Then ask it to check its own work in the way a person would:
+## 3. Connect your model: Settings > Models (5 minutes)
 
-> Do it now, without asking for approval. Click "New card" twice, look at the board, and tell me whether the counts agree.
+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.
 
-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.
+![Settings > Models with the DeepSeek key field](/docs-assets/workshop/s2-settings-models.webp)
 
-**Stuck?** If the agent says it cannot see a page, reload the app's tab: the page connects to the door when it loads.
+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.
 
-## 4. The same app in a desktop window (15 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.
 
-**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.
+**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
-npx acrylblends add desktop
-npm install
-npm run desktop
-```
+## 4. Chat: your model works on the app (20 minutes)
 
-The first `npm run desktop` downloads Electron (about 200 MB), then the window attaches to the running server and says so:
+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:
 
-```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)
-```
+> 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.
 
-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.
+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**.
 
-![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)
+![The AcrylDSH Chat tab with the request, beside the app](/docs-assets/workshop/s3-chat.webp)
 
-Then hand the agent the window itself, not only the page inside it. Ask:
+Every model builds a slightly different board: yours may need a title typed before "New card" adds one, or keep the sidebar always open.
 
-> 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?** 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".
 
-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.
+## 5. A coding agent in a terminal tab (15 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.
+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:
 
-![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)
+> 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.
 
-**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.
+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.
 
-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.
+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?** 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?** 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.
 
-## 5. Deploy it, then publish it (15 minutes)
+## 6. Upgrade an older app onto the frame (10 minutes)
 
-**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.
+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
-NODE_ENV=production npm start
+cd old-app
+npx acrylblends@latest upgrade
+npm install
+npm run dev
 ```
 
-(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.
+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.
 
-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`):
-
-| 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` |
+**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/`).
 
-Nothing in the app assumes ACRYL's own infrastructure: it is one Node process, one port, and its data in `.acrylblends/` next to it.
+## 7. Publish it as a starter (10 minutes, take-home)
 
-**Publish it as a starter.** Your app already is one: `blend.yaml` names it, `plugins/` holds its code.
+Your app already is a starter: `blend.yaml` names it, `plugins/` holds its code.
 
 ```sh
 cd ~/acryl-workshop
@@ -241,29 +236,18 @@ commit` as two lines, or join them with `;`.)
 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`.
 
-![The workshop registry's page, listing the starters other people published](/docs-assets/workshop/s6-registry.webp)
-
-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").
-
-**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.
+**Stuck?** The registry's check comments what to change; fix, commit, push again. `gh auth status` not logged in means `gh auth login`.
 
 ## Browser only (WebBoxes.ai) TODO(M9)
 
-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 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.
+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>. 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.
+- **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.
 
 ---
@@ -274,11 +258,13 @@ yours.
 | --- | --- |
 | 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` / `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 |
+| 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 `;` |
-| 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 |