acrylblends 1.0.2 → 1.0.3

package/docs/framework/README.md

@@ -54,6 +54,7 @@ They are enabled as they are built.
 | Look up a call | [API](api/index.md), [Routing](api/routing.md), [Context](api/context.md), [Request](api/request.md), [API summary](api/summary.md) |
 | Understand the design | [Concepts](concepts/motivation.md) |
 | Copy a pattern | [Guides](guides/best-practices.md), [Validation](guides/validation.md), [Testing](guides/testing.md), [Data, migrations and choosing a store](guides/data.md), [Forms, sessions and a database](guides/forms-and-sessions.md), [Client components without a bundler](guides/client-modules.md), [Bring your own tool](guides/bring-your-own-tool.md) |
+| Run the 90-minute workshop | [Workshop](workshop/README.md), and the room around it in [Facilitator notes](workshop/facilitator.md) |
 | Use Acryl inside a Cordis app | [Acryl in a Cordis app](cordis/acryl-in-a-cordis-app.md), [Plugin lifecycle](cordis/plugin-lifecycle.md), [Mounting](cordis/mounting.md) |
 | Move from the 0.3 router calls | [Migration from 0.3](cordis/migration-from-0-3.md) |
 | Know what runs in production, and what the sandbox stops | [What runs in production](guides/production.md) |

package/docs/framework/agents/index.md

@@ -47,7 +47,7 @@ npm run dev
 ```
 
 - `add` puts the `agent-panel` row (and `driver-pty`'s after it) in `blend.yaml` before the `routes` row and registers both in `src/app.ts`. On an app without the `agent` and `extensions` rows, such as `blank`, it refuses before it copies anything and says which rows are missing.
-- **The panel's coding agents are yours.** `claude`, `codex` and `pi` run on the machine that runs the app, in the app folder, with the login of the person who started it: `claude` and `codex` use their own signed-in sessions, and `pi` is offered when `DEEPSEEK_API_KEY` is set or `pi` has stored a DeepSeek login (`~/.pi/agent/auth.json`). A program that is not installed, or is not logged in, is not offered; nothing is shared between machines, and a workshop laptop needs its own login. The panel's own `agent` (the offline scripted one) needs none.
+- **The panel's coding agents are yours.** `claude`, `codex` and `pi` run on the machine that runs the app, in the app folder, with the login of the person who started it: `claude` and `codex` use their own signed-in sessions, and `pi` is offered when `DEEPSEEK_API_KEY` is set or `pi` has stored a DeepSeek login (`~/.pi/agent/auth.json`, read from the `HOME` of the process that runs the app: an app started under another `HOME` does not see the login, and the panel then lists `pty:pi` but no chat `pi`). A program that is not installed, or is not logged in, is not offered; nothing is shared between machines, and a workshop laptop needs its own login. The panel's own `agent` (the offline scripted one) needs none.
 - `pi` has to be an executable on the `PATH`; a shell function that wraps the binary is fine as long as the binary itself is found by `which pi`.
 - `driver-pty` brings `node-pty`, which ships prebuilt binaries for macOS, Windows and Linux. npm 11 and pnpm warn that its install script was not run (they ask you to approve dependency install scripts); you can ignore the warning. If no `pty:` terminal is offered and the app prints why at start, approve and rebuild: `npm approve-scripts node-pty`, then `npm rebuild node-pty` (pnpm: `pnpm approve-builds`).
 

package/docs/framework/guides/data.md

@@ -142,6 +142,18 @@ CREATE TABLE tags (
 - A database whose version is newer than your files (an older build started on newer data) is refused. The app does not start.
 - A migration is plain SQL. Put the data change next to the shape change in the same file when they belong together.
 
+**In an app made by `acrylblends init`** (a Cordis app) the provider is a row of `blend.yaml` (and an entry in the `registry` of `src/app.ts`, which `acrylblends add db` prints how to write):
+
+```yaml
+    - id: db
+      name: acryl-db-sqlite
+      config:
+        path: data/app.sqlite
+        migrations: migrations
+```
+
+A relative `path` or `migrations` in a row is read from the app's folder (the one that holds `blend.yaml`), not from where the command was started. (Since 1.0.3; before it a relative path stopped the app with "no file base URL", and an absolute path, or the `db: { migrations: join(projectRoot, 'migrations') }` option of `compose` in `src/app.ts` as the notes template does, was the way.)
+
 To add a feature that needs a column or a table, the work is always the same three steps: write the next migration, change the store that
 reads and writes it, and change the handlers and views that use the store.
 

package/docs/framework/workshop/README.md

@@ -0,0 +1,381 @@
+# From nothing to your own app: 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.
+
+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.
+
+## What you need (10 minutes)
+
+| | 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 |
+
+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)
+
+```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`:
+
+```
+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.
+
+## 2. Change one thing (7 minutes)
+
+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:
+
+```ts
+      .get('/hello', (c) => c.json({ hello: 'workshop' }))
+```
+
+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.
+
+**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.
+
+## 3. Tests and the typecheck (8 minutes)
+
+Stop the server with `Ctrl-C`, then:
+
+```sh
+npm test
+npm run check
+```
+
+`npm test` ends with `ℹ pass 5`, `ℹ fail 0`. `npm run check` prints nothing when the types are clean.
+
+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?** `npm run check` complaining about your new line is the typechecker doing its job; the message says which type it expected.
+
+## 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.
+
+```sh
+npx acrylblends add acryl-kv-json
+npm install
+```
+
+`add` copies the plugin into `plugins/` and prints how to mount it. Three edits:
+
+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
+   ```
+
+2. `src/app.ts`: import the plugin and register it under that name:
+
+   ```ts
+   import * as kvJson from '../plugins/acryl-kv-json/src/index.ts'
+   ```
+
+   ```ts
+   export const registry = { 'acryl-router': router, 'acryl-node-server': nodeServer, 'acryl-kv-json': kvJson, routes }
+   ```
+
+3. `src/routes.ts`: declare the port and count visits in your route:
+
+   ```ts
+   import type {} from '../plugins/acryl-kv/src/cordis.ts'
+   ```
+
+   ```ts
+     inject: ['router', 'kv'],
+   ```
+
+   ```ts
+     .get('/hello', async (c) => {
+       const visits = await ctx.kv.update('visits', (n) => (n ?? 0) + 1)
+       return c.json({ hello: 'workshop', visits })
+     })
+   ```
+
+`npm run dev` again and open `/hello` twice: `visits` goes 1, 2. The file is `my-hero/.acrylblends/kv.json`.
+
+The relational port is `db`, with numbered SQL migrations:
+
+```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
+```
+
+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.
+
+```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') },
+```
+
+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?** `migrations "migrations" is relative, but this app has no file base URL` means the folder was named in `blend.yaml`; move it into
+`src/app.ts` as above. "no such table" means the file is not in `migrations/` at the app root.
+
+## 5. A desktop window (7 minutes)
+
+```sh
+npx acrylblends add desktop
+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.
+
+## 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
+```
+
+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.
+
+For the workshop's own registry, name it:
+
+```sh
+npm create acrylblends@latest from-the-workshop -- --from <id> --registry github:acryldev/workshop-2026-11-20
+```
+
+Starters for this workshop: `acrylblends.notes-desktop` (notes with a desktop window), `acrylblends.chat`, `acrylblends.agent`.
+
+**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.
+
+## 7. Create from a template (7 minutes)
+
+Every app begins from one of six templates, the same list in `npm create acrylblends` and `acrylblends init`:
+
+| 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 |
+
+Try the one with a database and accounts, in a window:
+
+```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?** The sign-in page is at `/login`; the root redirects there. Delete the folder when you are done with it.
+
+## 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.
+
+```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
+```
+
+`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.
+
+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. 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).
+
+## 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.
+
+```sh
+cd ~/acryl-workshop/my-hero
+npx acrylblends@latest upgrade --dry-run
+npx acrylblends@latest upgrade
+npm install && npm test
+```
+
+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:
+
+   ```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
+   ```
+
+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`.
+
+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`.
+
+> **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.
+
+## 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.
+- **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 |
+| --- | --- |
+| `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 |
+| 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.

package/docs/framework/workshop/facilitator.md

@@ -0,0 +1,107 @@
+# Facilitator notes: the 90-minute ACRYL Blends workshop
+
+Read the attendee handout first (`docs/framework/workshop/README.md`); this page is the room around it: what to put on each machine, what actually breaks, and
+where to cut when the clock runs. Every timing and every failure below was measured on the published `acrylblends` 1.0.0 during the readiness walk
+(`docs/plans/workshop-readiness.md`).
+
+## Before the room: put this on every machine
+
+| What | Why | How |
+| --- | --- | --- |
+| Node.js 22.19 or newer (24 LTS or 26 tested), npm 11 | the app runs TypeScript directly, no build step | `node -v`; if missing, the LTS from nodejs.org or `brew install node` (Node 26 today, which is tested) |
+| git | the registry block clones the registry | `git --version` |
+| A warm npm cache | the first `npm create` downloads the initializer, `npm install` downloads Electron | create one app and add the desktop shell once per machine (below) |
+| A coding agent, logged in | step 7 drives Codex or Claude Code through the panel | `codex login status` or run `claude` once |
+| `~/acryl-workshop/prepared/` | the no-network fallback and the reset | copy the two prepared apps (below) |
+| A GitHub account with `gh auth login` | step 10 forks the workshop registry and opens a pull request | `gh auth status` |
+| A device with `git` and a text editor | the edits in steps 2, 4 and 8 are small but real | `git --version` |
+
+Warm-up, once per machine (this is also the exact smoke test that the room works):
+
+```sh
+mkdir -p ~/acryl-workshop && cd ~/acryl-workshop
+npm create acrylblends@latest warmup notes
+cd warmup && npm install && npm test
+npx acrylblends add desktop && npm install
+cd ~/acryl-workshop && cp -R warmup prepared-notes && rm -rf warmup
+```
+
+That leaves `prepared-notes` with everything installed, including Electron.
+
+## Timings, checkpoints, and what to make optional
+
+The handout's own timings, as measured on the published 1.0.2 (macOS, cold npm cache in a throwaway home):
+
+| Minutes | Step | Measured | If late |
+| --- | --- | --- | --- |
+| 0-10 | installs and checks | seconds each | never cut |
+| 10-15 | create and run the blank app | create 9 s cold (2 s warm), install 2 s, boot 2 s | never cut |
+| 15-22 | change one route | reload is instant | never cut |
+| 22-30 | tests and the typecheck | test 0.5-2 s, check 2.5-4 s | keep; cut the "write a test" exercise |
+| 30-38 | data: JSON then SQLite (**optional**) | two adds plus edits, ~8 min | **cut first** |
+| 38-45 | the desktop window | add 2 s, install 3 s, first Electron boot ~20 s | pre-warm Electron on every machine or demo it |
+| 45-53 | pull a starter | create 4 s, install 3 s, runs at once | keep; it is the fastest win in the room |
+| 53-60 | create from a template | create + install + add desktop 4 s | drop the second app |
+| 60-75 | the agent builds a feature | set-up 4 s; codex wrote a page and tests in about 7 minutes | never cut; demo it if the room is behind |
+| 75-82 | upgrade | seconds: a fresh app answers "everything is up to date" | keep; it is a 2-minute talk |
+| 82-90 | publish and the hero moment | the registry steps are seconds; the PR is talk | always keep at least the hero talk |
+
+Checkpoints in the handout, and what to look for as you walk the room: **15 minutes** every screen shows `{"app":"my-hero","ok":true}`; **45 minutes**
+every screen has the app in a desktop window; **75 minutes** every screen has `/board` open with the agent's page. A machine behind at a checkpoint is
+what the optional column is for, and the handout names the same choices so nobody has to guess.
+
+## What breaks in the room, and what to say
+
+These are the defects found by the walk. They are known; say so rather than letting people think they broke something.
+
+- **The data step is the slow one.** Wiring `kv` then `db` by hand is about ten minutes of edits for a newcomer (two rows, two registry lines, two
+  type imports, the migrations folder). It is the block the handout names optional, and the one to help with first.
+- **A relative migrations path in `blend.yaml` fails.** `migrations: migrations` in the row stops the app with "this app has no file base URL to
+  resolve it from". The folder is named in `src/app.ts`'s compose options instead; the handout teaches that form and the stuck line names the error.
+- **`pi` shows up only when the app can see its login.** 1.0.2 offers pi as a chat driver when `DEEPSEEK_API_KEY` is exported or `~/.pi/agent/auth.json`
+  holds a deepseek entry, read from the HOME the app runs in. On a normal attendee machine it is there; in a run with a moved HOME it is not (and pi
+  would fail on its first message anyway). `pty:pi` needs only the program.
+- **The agent run takes minutes, not seconds.** Codex wrote the page and its tests in about seven; tell the room to start it and keep talking.
+- **Publishing.** The workshop registry is `github.com/acryldev/workshop-2026-11-20`, public and open. Attendees fork it, run
+  `node scripts/make-entry.mjs ../agent-app <login>.agent-app --description "..."`, push and open a pull request; a check merges it, usually well under
+  two minutes, and a refusal comes as a comment. Taking an app down is a pull request that removes its folder. Pulling is
+  `--from <id> --registry github:acryldev/workshop-2026-11-20` (rehearsed on 1.0.2: create 12 s, install 3 s, runs at once).
+- **Browser-only attendees (TODO(M9)).** The handout's hosted-workspace stub is empty until M9 is live; until then a browser-only attendee can follow
+  along but not create an app.
+- **node-pty's install script (C5).** `npm install` warns that npm 11 blocked `node-pty`'s script. The terminal drivers still list; the workshop does
+  not open one.
+
+## The no-network fallback
+
+If the venue has no reliable network:
+
+1. Every machine gets `prepared-notes` and a prepared agent app from the sheet above, so steps 1-6 skip creation and installs.
+2. Step 8 uses the cloned registry and the installed `blends-core`; no network needed.
+3. Step 7 needs the agent's own model, so it cannot run offline. Demo it from your machine on a tethered connection, or record it (a 4-minute
+   screen recording of the codex run is enough).
+4. Keep one machine on a phone hotspot for `npm create` failures.
+
+## Demo script for the agent block (5 minutes, if you demo instead of hands-on)
+
+1. On the prepared agent app: `npm run dev`, open the page, click the panel button.
+2. Ask: "Add a route GET /agent-built to src/routes.ts that returns {\"built\": true}, then run the tests and tell me what happened."
+3. Narrate while it runs: the agent reads `AGENTS.md`, reads `docs/framework`, edits `src/routes.ts`, runs the tests; the terminal prints
+   `Change detected … Restarting`; reload `/agent-built` and show `{"built":true}`.
+4. Point at the panel's stop button and the audit line the panel writes under `.acrylblends/audit/`.
+
+## Resetting between sessions
+
+Everything a person makes lives inside their app folder and `~/acryl-workshop`. To reset a machine:
+
+```sh
+rm -rf ~/acryl-workshop/[a-z]*-app ~/acryl-workshop/registry
+cp -R ~/acryl-workshop/prepared/* ~/acryl-workshop/    # if you keep a prepared/ folder
+```
+
+Nothing is installed globally except the agent and Bun; neither needs cleaning between sessions.
+
+## What is still open
+
+- Starter pull (B1), the panel's rows (C1) and the upgrade command in the docs (B2) are with the framework team; when they land, the handout's
+  TODO lines become normal steps and this page's "what breaks" list shrinks.
+- The Windows and Linux runs of the attendee handout are being replayed separately; add what differs to the handout's OS column rather than here.

package/lib/cordis/db-sqlite.js

@@ -15,6 +15,10 @@ import z from "@deepseek-ai/schemastery";
 */
 /** Stable Cordis plugin name, equal to the package name and the Loader row id. */
 const name = "acryl-db-sqlite";
+/** The project folder of an acrylblends app (`appInstance.root`), when the instance has one: where a relative path in a row's config is read from, since such an app has no Loader base URL. */
+function appRoot(value) {
+	return typeof value === "object" && value !== null && "root" in value && typeof value.root === "string" ? value.root : void 0;
+}
 function isAppHome(value) {
 	return typeof value === "object" && value !== null && "home" in value && typeof value.home === "string";
 }
@@ -26,12 +30,16 @@ const Config = z.object({
 });
 /** The file name used in the app home when `path` is not configured. */
 const DEFAULT_FILE = "data.sqlite";
-/** A configured path as a file path: absolute as given, relative to the Loader's base URL (the app) otherwise. */
+/** A configured path as a file path: absolute as given, relative to the Loader's base URL (the app) otherwise, or to the app's project folder (`appInstance.root`) where there is no base URL. */
 function resolveFromApp(ctx, path, option) {
 	if (path.startsWith("file:")) return fileURLToPath(path);
 	if (isAbsolute(path)) return path;
 	const base = ctx.baseUrl;
-	if (base === void 0 || !base.startsWith("file:")) throw new Error(`acryl-db-sqlite: ${option} ${JSON.stringify(path)} is relative, but this app has no file base URL to resolve it from; give an absolute path`);
+	if (base === void 0 || !base.startsWith("file:")) {
+		const root = appRoot(ctx.get("appInstance"));
+		if (root !== void 0) return resolve(root, path);
+		throw new Error(`acryl-db-sqlite: ${option} ${JSON.stringify(path)} is relative, but this app has no file base URL to resolve it from; give an absolute path`);
+	}
 	return resolve(base.endsWith("/") ? fileURLToPath(base) : dirname(fileURLToPath(base)), path);
 }
 async function apply(ctx, rawConfig = {}) {

package/lib/cordis/kv-json.js

@@ -19,12 +19,20 @@ function isAppHome(value) {
 const Config = z.object({ path: z.string().description("The JSON file, absolute or relative to the app. Defaults to kv.json in the ACRYL app home; required where there is none.") });
 /** The file name used in the app home when `path` is not configured. */
 const DEFAULT_FILE = "kv.json";
-/** A configured path as a file path: absolute as given, relative to the Loader's base URL (the app) otherwise. */
+/** The project folder of an acrylblends app (`appInstance.root`), when the instance has one: where a relative path in a row's config is read from, since such an app has no Loader base URL. */
+function appRoot(value) {
+	return typeof value === "object" && value !== null && "root" in value && typeof value.root === "string" ? value.root : void 0;
+}
+/** A configured path as a file path: absolute as given, relative to the Loader's base URL (the app) otherwise, or to the app's project folder (`appInstance.root`) where there is no base URL. */
 function resolveFromApp(ctx, path) {
 	if (path.startsWith("file:")) return fileURLToPath(path);
 	if (isAbsolute(path)) return path;
 	const base = ctx.baseUrl;
-	if (base === void 0 || !base.startsWith("file:")) throw new Error(`acryl-kv-json: path ${JSON.stringify(path)} is relative, but this app has no file base URL to resolve it from; give an absolute path`);
+	if (base === void 0 || !base.startsWith("file:")) {
+		const root = appRoot(ctx.get("appInstance"));
+		if (root !== void 0) return resolve(root, path);
+		throw new Error(`acryl-kv-json: path ${JSON.stringify(path)} is relative, but this app has no file base URL to resolve it from; give an absolute path`);
+	}
 	return resolve(base.endsWith("/") ? fileURLToPath(base) : dirname(fileURLToPath(base)), path);
 }
 async function apply(ctx, rawConfig = {}) {

package/lib/cordis/node-server.js

@@ -1,4 +1,4 @@
-import { c as Request, i as createAdaptorServer, l as RequestError, n as UpgradeEmitter, r as UpgradeHub, t as testWebSocket } from "../test-websocket-ZXHNHQSU.js";
+import { c as Request, i as createAdaptorServer, l as RequestError, n as UpgradeEmitter, r as UpgradeHub, t as testWebSocket } from "../test-websocket-D8WWqE5G.js";
 import { t as serveStatic } from "../serve-static-3uo_9rjF.js";
 import { Service } from "@deepseek-ai/cordis";
 import z from "@deepseek-ai/schemastery";

package/lib/cordis/router-http.js

@@ -1,4 +1,4 @@
-import { n as UpgradeEmitter, r as UpgradeHub } from "../test-websocket-ZXHNHQSU.js";
+import { n as UpgradeEmitter, r as UpgradeHub } from "../test-websocket-D8WWqE5G.js";
 import "./node-server.js";
 import { Readable } from "node:stream";
 import { Service } from "@deepseek-ai/cordis";

package/lib/node-server.js

@@ -1,4 +1,4 @@
-import { a as serve, i as createAdaptorServer, l as RequestError, n as UpgradeEmitter, o as upgradeWebSocket, r as UpgradeHub, s as getRequestListener, t as testWebSocket } from "./test-websocket-ZXHNHQSU.js";
+import { a as serve, i as createAdaptorServer, l as RequestError, n as UpgradeEmitter, o as upgradeWebSocket, r as UpgradeHub, s as getRequestListener, t as testWebSocket } from "./test-websocket-D8WWqE5G.js";
 import { t as serveStatic } from "./serve-static-3uo_9rjF.js";
 import { getConnInfo } from "./node-server/conninfo.js";
 import { n as clientModules, t as buildClientModules } from "./client-modules-CLvWOjbd.js";

package/lib/{test-websocket-ZXHNHQSU.js → test-websocket-D8WWqE5G.js}

@@ -226,8 +226,7 @@ const readBodyBufferedBeforeDisconnect = (incoming, chunks) => {
 	else if (incomingWithRecovery[bodyBufferedLengthBeforeDisconnectKey] !== void 0 && incoming.readableLength !== incomingWithRecovery[bodyBufferedLengthBeforeDisconnectKey]) result = newBodyUnusableError();
 	else {
 		const bodyChunks = chunks ?? [];
-		const chunk = incoming.read();
-		if (chunk !== null) bodyChunks.push(toBufferChunk(chunk, incoming.readableEncoding));
+		for (let chunk = incoming.read(); chunk !== null; chunk = incoming.read()) bodyChunks.push(toBufferChunk(chunk, incoming.readableEncoding));
 		const buffer = bodyChunks.length === 1 ? bodyChunks[0] : Buffer.concat(bodyChunks);
 		result = buffer;
 		const contentLength = incoming.headers["content-length"];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "acrylblends",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "description": "The Acryl web framework (import { Acryl } from \"acrylblends\") and the acrylblends command that scaffolds Cordis apps.",
   "license": "MIT",
   "type": "module",

package/plugins/acryl-db-sqlite/plugin.json

@@ -8,7 +8,7 @@
     "@deepseek-ai/cordis": "4.0.4",
     "@deepseek-ai/schemastery": "3.18.4"
   },
-  "mount": "mount it after instance: root.plugin(dbSqlite, { migrations: 'migrations' }) with the migrations/ folder (001-name.sql, ...) next to src/; then a plugin that declares inject: ['db'] calls await ctx.db.all('SELECT ...', value)",
+  "mount": "mount it after instance, either as a row in blend.yaml (`- id: db` / `name: acryl-db-sqlite` / `config: { migrations: migrations }`, registered in src/app.ts as 'acryl-db-sqlite') or as root.plugin(dbSqlite, { migrations: 'migrations' }); a relative path is read from the app's folder, and the migrations/ folder (001-name.sql, ...) sits next to src/. Then a plugin that declares inject: ['db'] calls await ctx.db.all('SELECT ...', value)",
   "omit": ["**/*.test.*", "**/*.spec.*", "**/*.case.ts"],
   "imports": {
     "#acryl-db-sqlite": "acryl-db-sqlite/src/index.ts"