create-acrylblends 1.0.10 → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -131,7 +131,7 @@ Do not start timers inside a handler for keep-alives; let the plugin own one tim
131
131
  | `ctx.nodeServer.url`, `ctx.nodeServer.port` | `nodeServer` (`acryl-node-server`) | without the Host: one Node server for the whole router; options `hostname` (`127.0.0.1`), `port` (`0`), `scan` (`20`). See [Node server](../cordis/node-server.md) |
132
132
  | `ctx.state.cell(key, initial)` | `state` (`acryl-state`) | a writable cell owned by the plugin: `get()`, `set(value)`, `update(fn)`, `subscribe(fn)` returning an unsubscribe |
133
133
  | `ctx.state.derive(key, [cells], fn)` | `state` | a read-only cell computed from others |
134
- | `GET /api/state/:key`, `GET /api/state/:key/events` | `state` | each cell over the router, read-only; `useCell(cell)` from `acryl-state/react` in a React page |
134
+ | `GET /api/state/:key`, `GET /api/state/:key/events`, `GET /api/state/ws`, `GET /api/state/client.js` | `state` | each cell over the router, read-only; `watch(key, fn)` of `/api/state/client.js` follows keys in a page over one WebSocket (event streams as the fallback); `useCell(cell)` from `acryl-state/react` in a React page |
135
135
 
136
136
  Everything a plugin registers this way (mounts, cells, handlers) goes away when the plugin unloads, and comes back once when it reloads:
137
137
  see [Plugin lifecycle and disposal](../cordis/plugin-lifecycle.md).
@@ -48,6 +48,26 @@ Installing a plugin (`ctx.extensions.install`, the door's `plugin add`, the buil
48
48
  - It **stops**: reading any file outside the tool's own folder; writing files; starting child processes or workers; loading native addons; using the inspector. It gets an empty environment (no keys, no paths). It is killed after a time limit and capped in memory and output size. Calls are independent: nothing survives into the next one.
49
49
  - It **does not stop**: network access (Node 24 has no network permission: restrict egress outside the process where that matters), and it does not apply to plugins installed live (those are not run in the sandbox).
50
50
 
51
+ ## The address and the port
52
+
53
+ A server made from a template listens on `127.0.0.1` and starts looking for a free port at a number of its own (3100 and up, chosen from the app's folder). A hosting platform tells the process where to listen with `PORT`, and a container needs `0.0.0.0` to be reached from outside. The app reads four variables, in this order:
54
+
55
+ | What | First | Then | Otherwise |
56
+ | --- | --- | --- | --- |
57
+ | The port to start from (`0` for any free port) | `ACRYLBLENDS_PORT` | `PORT` | a number of its own, from the app's folder |
58
+ | The interface | `ACRYLBLENDS_HOST` | `HOST` | `127.0.0.1` (this machine only) |
59
+
60
+ `PORT` and `HOST` have been read since 1.1.0; before it, the `agent` and `blank` templates ignored `PORT` (`PORT=3299` still listened on the app's own number). If the port is taken the server tries the next ones, and the line it prints at start (`app listening on http://0.0.0.0:3299`) says which it got; a platform that routes to a fixed port should be given one that is free. For example, on a plain server:
61
+
62
+ ```sh
63
+ npm ci --omit=dev
64
+ NODE_ENV=production HOST=0.0.0.0 PORT=3299 npm start
65
+ # app listening on http://0.0.0.0:3299 (data in /srv/app/.acrylblends; ...)
66
+ curl http://127.0.0.1:3299/health
67
+ ```
68
+
69
+ Putting the app on `0.0.0.0` makes it reachable by anyone who can reach the machine: put the login or the proxy in front first (see the checklist below).
70
+
51
71
  ## Checklist for a deployment
52
72
 
53
73
  1. `NODE_ENV=production` (the process manager or the Dockerfile sets it; the templates' Dockerfile does).
@@ -1,191 +1,164 @@
1
- # From nothing to your own app: the ACRYL Blends workshop
1
+ # An app that builds and drives itself: the ACRYL Blends workshop
2
2
 
3
- 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
4
- `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
5
- `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
6
- 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
7
- starter other people can pull from the registry.
3
+ 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
4
+ 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
5
+ 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
6
+ around it: a folder of Cordis plugins with a `blend.yaml`, running on your machine, with an agent living inside its panel.
8
7
 
9
- 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
10
- are on time.
8
+ Two things make this workshop different from clicking through a tutorial: you write very little code (the agent writes the interface, you direct and
9
+ edit it), and the agent is not a sidebar chat about the code, it is a hand on the app.
11
10
 
12
- ## What you need (10 minutes)
11
+ This guide is for **acrylblends 1.0.10 or newer**; `npm create acrylblends@latest` gives you that.
13
12
 
14
- | | macOS | Windows | Linux |
15
- | --- | --- | --- | --- |
16
- | Node.js 22.19 or newer (24 LTS or 26 tested) | `node -v` | `node -v` | `node -v` |
17
- | npm, which comes with Node | `npm -v` | `npm -v` | `npm -v` |
18
- | git | `git --version` | `git --version` | `git --version` |
19
- | a coding agent, logged in | `codex login status` or `claude --version` | same | same |
20
- | a GitHub account and the `gh` CLI, logged in | `gh auth status` | same | same |
13
+ ## 0. Before you start (10 minutes)
21
14
 
22
- Install what is missing: Node from <https://nodejs.org> (the LTS), git from <https://git-scm.com>, the GitHub CLI (`brew install gh`, `winget
23
- 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
24
- `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;
25
- every new word is explained where it appears.
26
-
27
- Make a folder and open a terminal in it:
15
+ Run this first. It checks everything below and prints one line per check, with the exact command for anything missing:
28
16
 
29
17
  ```sh
30
- mkdir ~/acryl-workshop && cd ~/acryl-workshop
18
+ npx acrylblends@latest preflight
31
19
  ```
32
20
 
33
- ## The path
21
+ 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
22
+ first blocks do without (`gh` is only needed in block 5).
34
23
 
35
- | Minutes | Step | What you get |
36
- | --- | --- | --- |
37
- | 0-10 | Before you start | tools installed and checked |
38
- | 10-15 | 1. Create and run | a blank app answering in a browser |
39
- | 15-22 | 2. Change one thing | a route of your own, live, without a restart |
40
- | 22-30 | 3. Tests and the typecheck | the app proves itself |
41
- | 30-38 | 4. Data: JSON, then SQLite *(optional)* | a counter kept in a file, then in SQL |
42
- | 38-45 | 5. A desktop window | the same app as a window |
43
- | 45-53 | 6. Pull a starter from the registry | someone else's app in your folder |
44
- | 53-60 | 7. Create from a template | the six starters, one table, one run |
45
- | 60-75 | 8. An agent builds a feature | your app changed by the agent, still running |
46
- | 75-82 | 9. Upgrade | the app moved to the current framework |
47
- | 82-90 | 10. Publish it | your app as a registry starter |
48
-
49
- > **Checkpoint 15 minutes:** your app answers in a browser. Without that, read the "Stuck?" line of step 1.
50
- > **Checkpoint 45 minutes:** your app is open in a desktop window. Behind? Step 4 is the optional one; skip it and carry on.
51
- > **Checkpoint 75 minutes:** the agent's page is live. Still waiting? Give it five more minutes, then skip step 9.
52
-
53
- ## 1. Create and run (5 minutes)
24
+ | | macOS | Windows | Linux |
25
+ | --- | --- | --- | --- |
26
+ | Node.js 22.19 or newer (24 and 26 work) | `node -v` | `node -v` | `node -v` |
27
+ | git | `git --version` | `git --version` | `git --version` |
28
+ | one coding agent, logged in | `codex login status` or `claude --version` or `pi --version` | same | same |
29
+ | GitHub account and `gh`, for the last block | `gh auth status` | same | same |
54
30
 
55
- ```sh
56
- npm create acrylblends@latest my-hero blank
57
- cd my-hero
58
- npm install
59
- npm run dev
60
- ```
31
+ 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
32
+ login` once), and one agent:
61
33
 
62
- You should see:
34
+ - **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
35
+ your account supports (`/model` inside codex, or `model = "..."` in `~/.codex/config.toml`).
36
+ - **Claude Code**: <https://claude.com/claude-code>, then run `claude` once to log in.
37
+ - **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
38
+ starts pi from the app, so pi sees that terminal's environment). The preflight checks the key: `PASS agent pi (DeepSeek key found)`.
63
39
 
64
- ```
65
- created my-hero (blank) in /Users/you/acryl-workshop/my-hero: … files, plugins instance, acryl-router, acryl-node-server, manifest, save
40
+ | macOS and Linux | Windows PowerShell | Windows cmd.exe |
41
+ | --- | --- | --- |
42
+ | `export DEEPSEEK_API_KEY=sk-...` | `$env:DEEPSEEK_API_KEY="sk-..."` | `set DEEPSEEK_API_KEY=sk-...` |
66
43
 
67
- Next:
68
- cd my-hero
69
- npm install
70
- npm run dev
71
- ```
44
+ No prior knowledge of ACRYL, Cordis or Blends is needed; every new word is explained where it appears.
72
45
 
73
- then, from `npm run dev`:
46
+ Make the workshop folder:
74
47
 
75
- ```
76
- my-hero listening on http://127.0.0.1:3080 (data in /Users/you/acryl-workshop/my-hero/.acrylblends)
77
- ```
48
+ | macOS and Linux | Windows PowerShell | Windows cmd.exe |
49
+ | --- | --- | --- |
50
+ | `mkdir ~/acryl-workshop && cd ~/acryl-workshop` | `mkdir ~/acryl-workshop` then `cd ~/acryl-workshop` | `mkdir %USERPROFILE%\acryl-workshop` then `cd %USERPROFILE%\acryl-workshop` |
78
51
 
79
- Open that address: `{"app":"my-hero","ok":true}`. `/health` answers `{"ok":true}` too. Leave the terminal running.
52
+ **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
53
+ them with `;`. PowerShell 7 (`pwsh`) accepts `&&`. In cmd.exe, `Ctrl-C` asks `Terminate batch job (Y/N)?`: answer `Y`.
80
54
 
81
- **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
82
- seconds.
55
+ **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
56
+ 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
57
+ one sentence is the difference between watching and building.
83
58
 
84
- ## 2. Change one thing (7 minutes)
59
+ ## The path
85
60
 
86
- 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
87
- indentation of the lines around it:
61
+ | Minutes | Block | What you get |
62
+ | --- | --- | --- |
63
+ | 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 |
64
+ | 10-40 | 2. The agent builds the interface | a board page with cards, a sidebar and live counts, written by the agent from inside |
65
+ | 40-60 | 3. The agent drives the app | the agent opening the sidebar and ticking a card while you watch |
66
+ | 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 |
67
+ | 75-90 | 5. Deploy it, then publish it | the app running as a server, then listed in the registry |
88
68
 
89
- ```ts
90
- .get('/hello', (c) => c.json({ hello: 'workshop' }))
69
+ > **Checkpoint 10 minutes:** your route answers in the browser.
70
+ > **Checkpoint 40 minutes:** the agent's board is on screen.
71
+ > **Checkpoint 60 minutes:** the agent has clicked through the page by itself.
72
+ > **Checkpoint 75 minutes:** the same app is in a desktop window.
73
+
74
+ ## 1. The core in one breath (10 minutes)
75
+
76
+ ```sh
77
+ npm create acrylblends@latest my-app agent
78
+ cd my-app
79
+ npm install
80
+ npm run dev
91
81
  ```
92
82
 
93
- Save. The terminal prints `Change detected … Restarting 'src/main.ts'`, and `http://127.0.0.1:3080/hello` answers `{"hello":"workshop"}`. No restart
94
- command, no build step: the app watches its own source.
83
+ 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
84
+ this app. It is the `agent` template.
95
85
 
96
- **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.
86
+ ![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)
97
87
 
98
- ## 3. Tests and the typecheck (8 minutes)
88
+ 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
89
+ Acryl app is a function from a request to a response.
99
90
 
100
- Stop the server with `Ctrl-C`, then:
91
+ Open `src/routes.ts` and add one line to the chain, just above `.get('/health', …)`, keeping the indentation of the lines around it:
101
92
 
102
- ```sh
103
- npm test
104
- npm run check
93
+ ```ts
94
+ .get('/hello', (c) => c.json({ hello: 'workshop' }))
105
95
  ```
106
96
 
107
- `npm test` ends with `ℹ pass 5`, `ℹ fail 0`. `npm run check` prints nothing when the types are clean.
97
+ 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
98
+ `Restarting` line), and `/hello` answers `{"hello":"workshop"}`. Stop the server (`Ctrl-C`; in cmd.exe answer `Y`), run `npm test` and `npm run check`:
99
+ both pass (`npm test` reports 14 passing tests). That is the whole core: a route, a test, a typecheck.
108
100
 
109
- 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`
110
- again; a failure names the file and line.
101
+ **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.
111
102
 
112
- **Stuck?** `npm run check` complaining about your new line is the typechecker doing its job; the message says which type it expected.
103
+ ## 2. The agent builds the interface (30 minutes)
113
104
 
114
- ## 4. Data: JSON, then SQLite (8 minutes, optional)
115
-
116
- 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.
105
+ Start the app (on pi, in the terminal where `DEEPSEEK_API_KEY` is set):
117
106
 
118
107
  ```sh
119
- npx acrylblends add acryl-kv-json
120
- npm install
108
+ npm run dev
121
109
  ```
122
110
 
123
- `add` copies the plugin into `plugins/` and prints how to mount it. Three edits:
111
+ Open the address it prints and click "Ask the agent". Ask it, in one message:
124
112
 
125
- 1. `blend.yaml`, before `- id: server`: add the provider row (the row's id is yours to pick; the name is the plugin):
113
+ > 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
114
+ > 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
115
+ > "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
116
+ > go to /board yourself and check it looks right, and tell me what you saw.
126
117
 
127
- ```yaml
128
- - id: kv
129
- name: acryl-kv-json
130
- ```
118
+ 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/`,
119
+ 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
120
+ 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
121
+ agent moves the page to `/board`, the panel comes along and keeps following the run.
131
122
 
132
- 2. `src/app.ts`: import the plugin and register it under that name:
123
+ ![The panel while the agent builds: the request, then Working... 0:04 below it](/docs-assets/workshop/s2-panel-building.webp)
133
124
 
134
- ```ts
135
- import * as kvJson from '../plugins/acryl-kv-json/src/index.ts'
136
- ```
125
+ ![The board the agent built: three columns with cards, and a sidebar with filters and counts](/docs-assets/workshop/s3-board.webp)
137
126
 
138
- ```ts
139
- export const registry = { 'acryl-router': router, 'acryl-node-server': nodeServer, 'acryl-kv-json': kvJson, routes }
140
- ```
127
+ 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;
128
+ 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
129
+ sidebar always open.
141
130
 
142
- 3. `src/routes.ts`: declare the port and count visits in your route:
131
+ **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
132
+ current panel and fixes with `npx acrylblends@latest upgrade`.
143
133
 
144
- ```ts
145
- import type {} from '../plugins/acryl-kv/src/cordis.ts'
146
- ```
134
+ ## 3. The agent drives the app (20 minutes)
147
135
 
148
- ```ts
149
- inject: ['router', 'kv'],
150
- ```
136
+ 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
137
+ `act` (click, type, select, press, scroll, wait, and `navigate` or `reload` the page).
151
138
 
152
- ```ts
153
- .get('/hello', async (c) => {
154
- const visits = await ctx.kv.update('visits', (n) => (n ?? 0) + 1)
155
- return c.json({ hello: 'workshop', visits })
156
- })
157
- ```
139
+ Ask it:
158
140
 
159
- `npm run dev` again and open `/hello` twice: `visits` goes 1, 2. The file is `my-hero/.acrylblends/kv.json`.
141
+ > 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
142
+ > look again and tell me what the counts say.
160
143
 
161
- The relational port is `db`, with numbered SQL migrations:
144
+ 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:
145
+ 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...`
146
+ 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
147
+ under two minutes, most of it the model thinking.
162
148
 
163
- ```sh
164
- npx acrylblends add acryl-db-sqlite
165
- mkdir migrations
166
- printf 'CREATE TABLE visits (id INTEGER PRIMARY KEY, at TEXT NOT NULL);\n' > migrations/001-visits.sql
167
- npm install
168
- ```
149
+ Then ask it to check its own work in the way a person would:
169
150
 
170
- 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
171
- there, not in the manifest, because a relative path in the manifest has no folder to resolve against.
151
+ > Do it now, without asking for approval. Click "New card" twice, look at the board, and tell me whether the counts agree.
172
152
 
173
- ```ts
174
- import * as dbSqlite from '../plugins/acryl-db-sqlite/src/index.ts'
175
- // in the registry: 'acryl-db-sqlite': dbSqlite
176
- const projectRoot = fileURLToPath(new URL('..', import.meta.url))
177
- // in the compose options next to server:
178
- db: { migrations: join(projectRoot, 'migrations') },
179
- ```
153
+ 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
154
+ first if you want to see them move.
180
155
 
181
- Then `inject: ['router', 'kv', 'db']` with `import type {} from '../plugins/acryl-db/src/cordis.ts'`, and in the route
182
- `await ctx.db.run('INSERT INTO visits (at) VALUES (?)', new Date().toISOString())` before the reply. The database is `my-hero/.acrylblends/data.sqlite`,
183
- and the migrations run at start, in order.
156
+ **Stuck?** If the agent says it cannot see a page, reload the app's tab: the page connects to the door when it loads.
184
157
 
185
- **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
186
- 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.
158
+ ## 4. The same app in a desktop window (15 minutes)
187
159
 
188
- ## 5. A desktop window (7 minutes)
160
+ **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
161
+ 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.
189
162
 
190
163
  ```sh
191
164
  npx acrylblends add desktop
@@ -193,189 +166,119 @@ npm install
193
166
  npm run desktop
194
167
  ```
195
168
 
196
- 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`,
197
- and the window's browser data stays inside `my-hero/.acrylblends/electron`. Close the window when you are done (`Cmd-Q`, `Alt-F4`).
198
-
199
- **Stuck?** The first `npm run desktop` downloads Electron (about 200 MB). No display (a bare server)? Skip this step; nothing later needs it.
169
+ The first `npm run desktop` downloads Electron (about 200 MB), then the window attaches to the running server and says so:
200
170
 
201
- ## 6. Pull a starter from the registry (8 minutes)
202
-
203
- The registry is where people publish starters: <https://acrylblends.github.io/blends> (the starters written for this framework say
204
- `runtime: acrylblends`; older ACRYL app starters are refused with a line saying so). Pull one by id, straight into a new folder:
205
-
206
- ```sh
207
- cd ~/acryl-workshop
208
- npm create acrylblends@latest from-the-registry -- --from <starter-id>
209
- cd from-the-registry
210
- npm install
211
- npm run dev
171
+ ```text
172
+ 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)
173
+ desktop: windows and menu are available to the door (acryl window list, acryl menu list)
212
174
  ```
213
175
 
214
- 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
215
- 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
216
- `Next:` block asks for the same `npm install` as step 1.
176
+ 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
177
+ 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.
217
178
 
218
- For the workshop's own registry, name it:
179
+ ![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)
219
180
 
220
- ```sh
221
- npm create acrylblends@latest from-the-workshop -- --from <id> --registry github:acryldev/workshop-2026-11-20
222
- ```
181
+ Then hand the agent the window itself, not only the page inside it. Ask:
223
182
 
224
- Starters for this workshop: `acrylblends.notes-desktop` (notes with a desktop window), `acrylblends.chat`, `acrylblends.agent`.
183
+ > 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.
225
184
 
226
- **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
227
- ACRYL app starter: open it in the ACRYL app`) and then npm's own error block; read the first lines, not the last.
185
+ 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
186
+ 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
187
+ Windows and Linux (`Ctrl+,`); it opens `/settings` in a window of its own.
228
188
 
229
- ## 7. Create from a template (7 minutes)
189
+ 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
190
+ 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
191
+ 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.
230
192
 
231
- Every app begins from one of six templates, the same list in `npm create acrylblends` and `acrylblends init`:
193
+ ![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)
232
194
 
233
- | Template | What you get |
234
- | --- | --- |
235
- | `blank` | the router, the server and one route: what you just built |
236
- | `nodejs` | a page rendered with JSX and a client component, without a bundler |
237
- | `notes` | a multi-user notes app on the `db` port: sign-up, sessions, migrations, search, a typed client |
238
- | `chat` | an answer streamed over server-sent events from an OpenAI-compatible API, history in SQLite |
239
- | `todo` | a to-do list on the router and live state |
240
- | `agent` | the blank app with an offline agent that writes and installs plugins into the running app |
195
+ **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.
241
196
 
242
- Try the one with a database and accounts, in a window:
197
+ 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
198
+ yourself or tell the agent it may.
243
199
 
244
- ```sh
245
- cd ~/acryl-workshop
246
- npm create acrylblends@latest notes-app notes
247
- cd notes-app && npm install
248
- npx acrylblends add desktop && npm install && npm run desktop
249
- ```
250
-
251
- 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`.
200
+ **Stuck?** On Ubuntu 23.10+ the launch starts with `--no-sandbox` and says why; the AppArmor route is in
201
+ `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
202
+ it and ask again.
252
203
 
253
- **Stuck?** The sign-in page is at `/login`; the root redirects there. Delete the folder when you are done with it.
204
+ ## 5. Deploy it, then publish it (15 minutes)
254
205
 
255
- ## 8. An agent builds a feature (15 minutes)
256
-
257
- 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,
258
- tools and memory), so this step builds a second, small app from that template; it is the app you publish in step 10.
206
+ **Deploy the app without its agent.** The agent, the panel and the terminal driver are development tools: with `NODE_ENV=production` they start
207
+ 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.
259
208
 
260
209
  ```sh
261
- cd ~/acryl-workshop
262
- npm create acrylblends@latest agent-app agent
263
- cd agent-app
264
- npm install
265
- npx acrylblends add agent-panel driver-pty
266
- npx acrylblends add desktop
267
- npm install
268
- npm run dev
210
+ NODE_ENV=production npm start
269
211
  ```
270
212
 
271
- `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
272
- 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
273
- `claude`, or `pi` when pi has its DeepSeek login in your home folder), and ask:
213
+ (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
214
+ PowerShell.) It prints `extensions (read-only): board`: the board the agent installed runs, and nothing can install or remove a plugin.
274
215
 
275
- > Add a page at /board that lists the app's tasks, newest first, and a test for it.
216
+ 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
217
+ `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
218
+ `ACRYLBLENDS_HOST` and `ACRYLBLENDS_PORT` (not `PORT`):
276
219
 
277
- 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
278
- few minutes; the panel shows each step, and has a stop button. Open `/board` when it is done.
279
-
280
- 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
281
- the door (`.acryl/bin/acryl`) to look at the page it built.
282
-
283
- **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
284
- `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
285
- `npm rebuild node-pty` (the `add` output says the same).
220
+ | macOS and Linux | Windows PowerShell | Windows cmd.exe |
221
+ | --- | --- | --- |
222
+ | `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` |
286
223
 
287
- ## 9. Upgrade (7 minutes)
224
+ Nothing in the app assumes ACRYL's own infrastructure: it is one Node process, one port, and its data in `.acrylblends/` next to it.
288
225
 
289
- 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:
290
- **`npx acrylblends@latest`**, because an app's own copy of `acrylblends` shadows the bare command and an older copy has no `upgrade` at all.
226
+ **Publish it as a starter.** Your app already is one: `blend.yaml` names it, `plugins/` holds its code.
291
227
 
292
228
  ```sh
293
- cd ~/acryl-workshop/my-hero
294
- npx acrylblends@latest upgrade --dry-run
295
- npx acrylblends@latest upgrade
296
- npm install && npm test
229
+ cd ~/acryl-workshop
230
+ gh repo fork acryldev/workshop-2026-11-20 --clone
231
+ cd workshop-2026-11-20
232
+ node scripts/make-entry.mjs ../my-app <your-github-login>.my-app --description "the board my agent built"
233
+ git add blends && git commit -m "add <your-github-login>.my-app"
234
+ git push
235
+ gh pr create --fill --repo acryldev/workshop-2026-11-20
297
236
  ```
298
237
 
299
- 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
300
- 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
301
- `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
302
- afterwards.
303
-
304
- ## 10. Publish it, and the hero moment (8 minutes)
305
-
306
- 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
307
- **starter**: `blend.yaml` names it, lists its rows, and `plugins/` holds its code. Two parts make it public: your own copy, then the registry.
308
-
309
- **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
310
- private app to a public remote). Create an empty repository on your git host, set it as `origin`, run `npm run save`.
311
-
312
- **The registry.** Publishing is a pull request to the workshop registry, `github.com/acryldev/workshop-2026-11-20`, and it is four commands.
313
-
314
- 1. Fork and clone it, then let its script build the entry from your app:
315
-
316
- ```sh
317
- cd ~/acryl-workshop
318
- gh repo fork acryldev/workshop-2026-11-20 --clone
319
- cd workshop-2026-11-20
320
- node scripts/make-entry.mjs ../agent-app <your-github-login>.agent-app --description "the app I built in the workshop"
321
- ```
238
+ (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
239
+ commit` as two lines, or join them with `;`.)
322
240
 
323
- `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`
324
- 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
325
- it, so whoever pulls it gets the desktop shell without adding it again. The id is lowercase, `<login>.<name>` with letters, digits and dashes.
241
+ 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
242
+ `npm create acrylblends@latest another-app -- --from <your-github-login>.my-app --registry github:acryldev/workshop-2026-11-20`.
326
243
 
327
- 2. Commit, push and open the pull request:
244
+ ![The workshop registry's page, listing the starters other people published](/docs-assets/workshop/s6-registry.webp)
328
245
 
329
- ```sh
330
- git add blends && git commit -m "add <your-github-login>.agent-app"
331
- git push
332
- gh pr create --fill --repo acryldev/workshop-2026-11-20
333
- ```
246
+ As an aside, for an app made before this release: `npx acrylblends@latest upgrade` moves the framework plugins it carries to the installed version,
247
+ leaving your own code alone (an app you made today answers "everything is up to date").
334
248
 
335
- 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
336
- 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:
337
- `git rm -r blends/<your-github-login>.agent-app`.
249
+ **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
250
+ with no agent is correct: that is the design, not a missing piece.
338
251
 
339
- Anyone can then start from it, in the browser or in a window:
340
-
341
- ```sh
342
- npm create acrylblends@latest my-app -- --from <your-github-login>.agent-app --registry github:acryldev/workshop-2026-11-20
343
- ```
252
+ ## Browser only (WebBoxes.ai) TODO(M9)
344
253
 
345
- **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
346
- 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`.
254
+ 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
255
+ in the same folders. Nothing to install, nothing to keep on your machine.
347
256
 
348
- > **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
349
- > 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
350
- > 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.
257
+ 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
258
+ 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
259
+ yours.
351
260
 
352
261
  ## Where next
353
262
 
354
- - **Read the docs you already have**: every app carries `docs/framework`, the same pages as <https://acrylblends.github.io/docs>. Start with
355
- `cordis/acryl-in-a-cordis-app.md`, then `guides/data.md`, then `guides/production.md` (what runs in production, and what does not).
356
- - **Swap a provider by editing one row**: SQLite to Postgres (`npx acrylblends add acryl-db-postgres`), the browser to a window (`desktop`), one agent
357
- to another (the panel's driver list).
358
- - **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.
263
+ - **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
264
+ `agent/`, the data ports in `guides/data.md`, and `guides/production.md` says exactly what runs on a server.
265
+ - **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.
266
+ - **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.
359
267
  - **Bring your own tool**: <https://acrylblends.github.io/docs/guides/bring-your-own-tool> wraps an outside library as a provider of a port.
360
268
 
361
- ## Browser only (WebBoxes.ai) TODO(M9)
362
-
363
- 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
364
- folders. Nothing to install, nothing to keep on your machine.
365
-
366
- 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
367
- 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.
368
-
369
269
  ---
370
270
 
371
271
  ## If something goes wrong
372
272
 
373
273
  | Symptom | Do |
374
274
  | --- | --- |
275
+ | The preflight prints `FIX` lines | run each one, then `npx acrylblends@latest preflight` again |
375
276
  | `npm create` fails or hangs | check the network; the facilitator has prepared apps |
376
277
  | A port is taken | use the address the app printed |
377
- | The agent cannot log in | `codex login` / `claude` in a terminal, then retry in the panel |
378
- | You want to start over | delete your app folder and repeat step 1; nothing lives outside it |
278
+ | The agent cannot log in | `codex login` / `claude` / `pi` in a terminal, then retry in the panel |
279
+ | Codex answers `model_not_found` | pick a model your account supports: `/model` in codex, or `model = "..."` in `~/.codex/config.toml` |
280
+ | 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 |
281
+ | The agent plans and stops | reply "do it now"; the config asks it to act, but a model sometimes waits |
282
+ | `&&` is an error in PowerShell | Windows PowerShell 5.1: type the two commands as two lines, or join them with `;` |
283
+ | The agent says it acted, but the desktop window did not change | close the app's browser tab, then ask again |
379
284
  | Anything else | the **Stuck?** line of the step, then your facilitator |
380
-
381
- 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.
@@ -1,108 +1,131 @@
1
- # Facilitator notes: the 90-minute ACRYL Blends workshop
1
+ # Facilitator notes: an app that builds and drives itself
2
2
 
3
- 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
4
- 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
5
- (`docs/plans/workshop-readiness.md`).
3
+ Read the handout first (`docs/framework/workshop/README.md`); this page is the room around it. The workshop changed shape on 2026-10-29: the agent living in
4
+ the app both builds its interface and drives it (clicks, sidebars, dialogs, settings), on the web and in a desktop window. The data layer and the template
5
+ tour are asides now, and `/hello` is only the introduction to the framework core. The handout is written for **acrylblends 1.0.10 or newer**.
6
6
 
7
7
  ## Before the room: put this on every machine
8
8
 
9
9
  | What | Why | How |
10
10
  | --- | --- | --- |
11
- | 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) |
12
- | git | the registry block clones the registry | `git --version` |
13
- | 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) |
14
- | A coding agent, logged in | step 7 drives Codex or Claude Code through the panel | `codex login status` or run `claude` once |
15
- | `~/acryl-workshop/prepared/` | the no-network fallback and the reset | copy the two prepared apps (below) |
16
- | A GitHub account with `gh auth login` | step 10 forks the workshop registry and opens a pull request | `gh auth status` |
17
- | A device with `git` and a text editor | the edits in steps 2, 4 and 8 are small but real | `git --version` |
11
+ | The preflight passing | it checks Node, npm, git, an agent with its login or key, a free port, and on Windows PowerShell and long paths | `npx acrylblends@latest preflight` ends with `Ready for the workshop.` |
12
+ | Node.js 22.19 or newer (24 and 26 tested) | the app runs TypeScript directly | `node -v`; the app's own `scripts/check-node.cjs` refuses an older Node with a clear line |
13
+ | git, and a GitHub account with `gh auth login` | the last block forks the workshop registry and opens a pull request | `git --version`, `gh auth status` |
14
+ | One coding agent, logged in | the panel drives it; `codex`, `claude` and `pi` all worked | `codex login` once (and a model the account supports), or run `claude` once, or pi with `DEEPSEEK_API_KEY` set in the terminal that starts the app |
15
+ | A prepared app with Electron already downloaded | the desktop block is 15 minutes and the download is the slowest part | run the handout's blocks 1 and 4 once per machine, then keep the folder as `~/acryl-workshop/prepared/` |
16
+ | A warm npm cache | the first `npm create` and the Electron download dominate the first ten minutes | the prepared app does it |
18
17
 
19
- Warm-up, once per machine (this is also the exact smoke test that the room works):
18
+ **The agent config that decides the day.** The panel's agent is configured to act rather than describe. Check on every machine that a plain request
19
+ produces files, not a plan: ask the prepared app's panel "say hello in a card on the page" and watch the panel's `Working...` line and the first file
20
+ appear. If it only describes, the model is waiting for permission; the handout's sentence is "do it now".
20
21
 
21
- ```sh
22
- mkdir -p ~/acryl-workshop && cd ~/acryl-workshop
23
- npm create acrylblends@latest warmup notes
24
- cd warmup && npm install && npm test
25
- npx acrylblends add desktop && npm install
26
- cd ~/acryl-workshop && cp -R warmup prepared-notes && rm -rf warmup
27
- ```
22
+ **Agent-specific checks.** Codex answering `model_not_found` means the account does not have the default model: pick one it supports (`/model` in codex,
23
+ or `model = "..."` in `~/.codex/config.toml`). pi with DeepSeek needs `DEEPSEEK_API_KEY` in the environment of the terminal that runs `npm run dev`
24
+ (the panel starts pi from the app); the preflight reports `PASS agent pi (DeepSeek key found)` when it is there. The package is
25
+ `@earendil-works/pi-coding-agent` (1.4.0 on npm on 2026-10-30), installed with `npm i -g @earendil-works/pi-coding-agent`.
28
26
 
29
- That leaves `prepared-notes` with everything installed, including Electron.
27
+ ## Timings, from the 1.0.10 walks (macOS and Windows, pi on DeepSeek)
30
28
 
31
- ## Timings, checkpoints, and what to make optional
32
-
33
- The handout's own timings, as measured on the published 1.0.2 (macOS, cold npm cache in a throwaway home):
34
-
35
- | Minutes | Step | Measured | If late |
29
+ | Minutes | Block | Measured | If late |
36
30
  | --- | --- | --- | --- |
37
- | 0-10 | installs and checks | seconds each | never cut |
38
- | 10-15 | create and run the blank app | create 9 s cold (2 s warm), install 2 s, boot 2 s | never cut |
39
- | 15-22 | change one route | reload is instant | never cut |
40
- | 22-30 | tests and the typecheck | test 0.5-2 s, check 2.5-4 s | keep; cut the "write a test" exercise |
41
- | 30-38 | data: JSON then SQLite (**optional**) | two adds plus edits, ~8 min | **cut first** |
42
- | 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 |
43
- | 45-53 | pull a starter | create 4 s, install 3 s, runs at once | keep; it is the fastest win in the room |
44
- | 53-60 | create from a template | create + install + add desktop 4 s | drop the second app |
45
- | 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 |
46
- | 75-82 | upgrade | seconds: a fresh app answers "everything is up to date" | keep; it is a 2-minute talk |
47
- | 82-90 | publish and the hero moment | the registry steps are seconds; the PR is talk | always keep at least the hero talk |
48
-
49
- 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**
50
- 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
51
- what the optional column is for, and the handout names the same choices so nobody has to guess.
52
-
53
- ## What breaks in the room, and what to say
54
-
55
- These are the defects found by the walk. They are known; say so rather than letting people think they broke something.
56
-
57
- - **An agent with its own settings acts differently.** Skills, hooks and instructions in a person's own Codex or Claude configuration travel into the panel's run: on the owner's laptop Codex stopped to "present a design for approval" instead of building. Word every task for the agent as "do it now, without asking for approval", and for a demo machine start the agent from a clean configuration (a fresh `CODEX_HOME`, no personal skills).
58
- - **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
59
- type imports, the migrations folder). It is the block the handout names optional, and the one to help with first.
60
- - **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
61
- 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.
62
- - **`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`
63
- 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
64
- would fail on its first message anyway). `pty:pi` needs only the program.
65
- - **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.
66
- - **Publishing.** The workshop registry is `github.com/acryldev/workshop-2026-11-20`, public and open. Attendees fork it, run
67
- `node scripts/make-entry.mjs ../agent-app <login>.agent-app --description "..."`, push and open a pull request; a check merges it, usually well under
68
- two minutes, and a refusal comes as a comment. Taking an app down is a pull request that removes its folder. Pulling is
69
- `--from <id> --registry github:acryldev/workshop-2026-11-20` (rehearsed on 1.0.2: create 12 s, install 3 s, runs at once).
70
- - **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
71
- along but not create an app.
72
- - **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
73
- not open one.
31
+ | 0-10 | preflight, setup and `/hello` | preflight 12 s; create, install, dev, the route edit, `npm test` (14 tests) and `npm run check` 14 s of commands | never cut |
32
+ | 10-40 | the agent builds the interface | 5:51 for pi to build, install and check the board (an earlier codex run: about 2.5 minutes) | if late, keep the board minimal (one column) |
33
+ | 40-60 | the agent drives the app | 1:41 for the tick-and-filter prompt (six door calls, most of the time the model thinking), 2:07 for the New-card prompt | the drive is the point; cut the second "check its own work" prompt |
34
+ | 60-75 | the same app in a window | add + install 5 s; first `npm run desktop` 10 s including the Electron download on a fast line; the drive in the window 22 s; the windows, menu and settings prompt 1:11 | pre-warm Electron or demo it |
35
+ | 75-90 | deploy and publish | production start in seconds; the registry check merges in about 2 minutes | keep the publish; the deploy talk can be 3 minutes |
36
+
37
+ The Windows walk on 1.0.10 (2026-10-30, Windows 10, Node 22, pi on DeepSeek) matched: preflight 13 s; `npm create` 8 s and install 4 s; pi built the
38
+ board from the panel in 5:56; the agent opened Settings through `File > Settings...`, set the appearance and saw `Saved: Dark`, and window 1 showed it
39
+ after a reload; with two windows open during a live run, `look` answered in 317-353 ms in each and the panel's Stop ended the run in 3 s; production served
40
+ the board read-only with the agent routes gone.
41
+
42
+ Checkpoints in the handout: 10 minutes a route answers; 40 minutes the agent's board is on screen; 60 minutes the agent has clicked through it; 75 minutes
43
+ the window is open. Walk the room at those minutes and help the machine that is behind, rather than the one that is ahead.
44
+
45
+ ## What to say in the room
46
+
47
+ - **Close the browser tab before block 4.** While a browser tab of the app is open, a door action without `--window` can go to that tab: in the 1.0.10
48
+ walk the agent, asked from the window's panel, moved the hidden browser tab and reported success while the window stayed on `/`. With the tab closed
49
+ the same prompt drove the window in 22 s. The handout says so at the top of block 4; it stays until the door aims at the window the agent was asked
50
+ from (reported to Blends).
51
+ - **The Settings item.** It is in the application menu on macOS (`my-app > Settings...`, `Cmd+,`) and the first item of the File menu on Windows and Linux
52
+ (`Ctrl+,`). An app gets it because it serves `/settings`; the template does. In the walk, pi found it in the app menu by itself.
53
+ - **Appearance.** The template's `/settings` saves light, dark or "match the system" for the app's own pages. A window that is already open shows the
54
+ change after a reload, and a page the agent built follows the system theme unless asked otherwise. On a dark-mode machine, demo with Light.
55
+ - **The driving bar.** `Agent is driving: clicking` with a Stop button shows at the bottom of the page only while each action runs, a moment each; the
56
+ panel's `Working... m:ss` line and its Stop button are what people see during a run.
57
+ - **Every agent builds a different board.** pi's board needed a title typed before "New card" added a card, and kept its sidebar always open when the
58
+ prompt did not ask for a toggle. The handout's block 2 prompt now asks for a button that opens and closes the sidebar, so block 3 has something to open.
59
+ - **Production listens where it is told.** The app reads `ACRYLBLENDS_HOST` and `ACRYLBLENDS_PORT`, not `PORT`; without them it listens on `127.0.0.1` at a
60
+ port chosen from its folder. A server needs `ACRYLBLENDS_HOST=0.0.0.0 ACRYLBLENDS_PORT=8080 NODE_ENV=production npm start` (verified: it answered on the
61
+ LAN). If Blends ships `PORT`, the handout switches to it.
62
+ - **Windows.** Windows PowerShell 5.1 has no `&&` (two lines, or `;`); PowerShell sets variables with `$env:NAME="value"`; cmd.exe's `Ctrl-C` asks
63
+ `Terminate batch job (Y/N)?` (answer `Y`); cmd.exe does not expand `~` (use `%USERPROFILE%`). Node 22 prints only `Restarting 'src/main.ts'` on a save;
64
+ Node 24 and 26 print `Change detected …` before it.
65
+ - **F (the door through a DeepSeek model with no login).** pi with a DeepSeek key works today; do not promise more than that.
66
+
67
+ ## What the 1.0.10 walk found, block by block
68
+
69
+ The final macOS walk on 1.0.10 (2026-10-30), verbatim from the handout as it stood before this revision, with pi on DeepSeek. Every block passed; these
70
+ are the places where the handout text differed from what the walk saw, and each one is now handled in the handout.
71
+
72
+ 1. Block 1: npm test now has 14 tests (the guide gives no number). "Change detected … Restarting" matches on Node 24; on Node 22 only "Restarting"
73
+ prints (seen on z370n).
74
+ 2. Block 2: "keep the app's own page (/) open in a second tab, because the panel lives there" is outdated: the panel is on every page now and followed the
75
+ agent to /board. The page is dark on a dark-mode Mac (screenshots s1-first-page/s3-board look different); the panel stays light on the dark page.
76
+ 3. Block 3: the guide's block 2 prompt asks for no sidebar toggle, so "open the sidebar" has nothing to open (pi says so and goes on). "an indicator in
77
+ the corner says the agent is driving, with a stop button": it shows only while each single door call runs (a fraction of a second), so an attendee
78
+ will hardly see it; it never showed in 33 frames taken every 3 s. "Click New card twice" added no cards: pi's board needs a title first; the prompt
79
+ only asks whether the counts agree. "seven door calls in about twenty seconds" was 6 calls in 1:41 with pi.
80
+ 4. Block 4: the guide says "use the File menu". On macOS Settings is in the app menu (my-app>Settings..., Cmd+,); pi found it there itself. Elsewhere it
81
+ is the first File item. "switch the appearance to dark" shows no change on a dark-mode Mac, and the agent-built /board ignores the app theme (its CSS
82
+ follows the system); the change shows on the template's / and /settings, and in other open windows only after a reload (switching to Light in window
83
+ 3, window 1 on / changed only after act reload). The TODO(1.0.4-C) paragraph is outdated: the window, menu and settings control has shipped.
84
+ Important: if the browser tab from blocks 2-3 is still open, the agent's door calls from the window's panel go to that browser tab, not the window. My
85
+ first in-window drive moved the hidden tab and the window stayed on /. With the tab closed it worked.
86
+ 5. Block 5: "That is the same app on any Node host … one port" names no port: the app binds 127.0.0.1 on a port derived from its folder path, ignores PORT
87
+ (PORT=3299 still gave 3991), and needs ACRYLBLENDS_PORT and ACRYLBLENDS_HOST (only the app's README names them; production.md does not).
74
88
 
75
89
  ## The no-network fallback
76
90
 
77
- If the venue has no reliable network:
91
+ 1. Prepared apps on every machine cover blocks 1-3; the agent's model still needs the network, so block 2 and 3 need a connection or a demo.
92
+ 2. Block 5's registry needs GitHub; if the venue is offline, publish from your machine on a hotspot at the end, or show the recording.
93
+ 3. Keep one phone hotspot for the room.
78
94
 
79
- 1. Every machine gets `prepared-notes` and a prepared agent app from the sheet above, so steps 1-6 skip creation and installs.
80
- 2. Step 8 uses the cloned registry and the installed `blends-core`; no network needed.
81
- 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
82
- screen recording of the codex run is enough).
83
- 4. Keep one machine on a phone hotspot for `npm create` failures.
95
+ ## Demo script (five minutes, if the room is behind)
84
96
 
85
- ## Demo script for the agent block (5 minutes, if you demo instead of hands-on)
97
+ 1. Prepared app, panel open: ask for a card with a count. Narrate the panel's `Working...` line and the page as it reloads.
98
+ 2. Ask: "open the sidebar, tick one card, change the filter to done, tell me the counts." Point at the page changing and at the driving bar as each action
99
+ runs.
100
+ 3. Show `.acryl/audit/` afterwards: every action is a line.
101
+ 4. Close the browser tab, switch to the desktop window and repeat one click there; then open Settings from the menu.
102
+ 5. Show the registry listing with an app already published, and the four commands that put it there.
86
103
 
87
- 1. On the prepared agent app: `npm run dev`, open the page, click the panel button.
88
- 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."
89
- 3. Narrate while it runs: the agent reads `AGENTS.md`, reads `docs/framework`, edits `src/routes.ts`, runs the tests; the terminal prints
90
- `Change detected … Restarting`; reload `/agent-built` and show `{"built":true}`.
91
- 4. Point at the panel's stop button and the audit line the panel writes under `.acrylblends/audit/`.
104
+ ## Screenshots
92
105
 
93
- ## Resetting between sessions
106
+ Taken on 1.0.10 on macOS in dark mode (the pages follow the system theme), 1280 wide, no personal data, tokens or real home paths:
94
107
 
95
- Everything a person makes lives inside their app folder and `~/acryl-workshop`. To reset a machine:
108
+ | File | Shows |
109
+ | --- | --- |
110
+ | `s1-first-page.webp` | the first page with the panel open (block 1) |
111
+ | `s2-panel-building.webp` | the panel with the build request and `Working... 0:04` (block 2) |
112
+ | `s3-board.webp` | a board an agent built (block 2; from an earlier run, kept because it shows the result best) |
113
+ | `s4-agent-drives-window.webp` | the agent driving the board in the desktop window: the Done filter it just set (block 4) |
114
+ | `s5-two-windows.webp` | two desktop windows: the app's page in the dark appearance, and the Settings window showing `Saved: Dark` (block 4) |
115
+ | `s6-registry.webp` | the registry listing (block 5) |
96
116
 
97
- ```sh
98
- rm -rf ~/acryl-workshop/[a-z]*-app ~/acryl-workshop/registry
99
- cp -R ~/acryl-workshop/prepared/* ~/acryl-workshop/ # if you keep a prepared/ folder
100
- ```
117
+ S4 and S5 are page captures of the desktop windows (through the window's DevTools), without the window frame; a capture with the frame needs the
118
+ screen-recording permission on the machine that takes it.
119
+
120
+ ## Resetting between sessions
101
121
 
102
- Nothing is installed globally except the agent and Bun; neither needs cleaning between sessions.
122
+ Everything a person makes lives inside their app folder and `~/acryl-workshop`. To reset a machine, delete the app folders and copy the prepared one back;
123
+ nothing is installed globally except the agent, `gh` and Node.
103
124
 
104
125
  ## What is still open
105
126
 
106
- - 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
107
- TODO lines become normal steps and this page's "what breaks" list shrinks.
108
- - 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.
127
+ - Close-the-tab advice in block 4 until the door aims at the window the agent was asked from.
128
+ - The appearance reaching open windows live, and an agent-built page following the app's appearance: reported to Blends; the handout says "reload".
129
+ - `PORT` for production: if Blends ships it, the handout's server line switches from `ACRYLBLENDS_PORT` to `PORT`.
130
+ - The handout's hosted-workspace section (browser-only attendees) stays TODO(M9) until that workspace is live; the one-click WebBoxes.ai deploy lives
131
+ there too.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "create-acrylblends",
3
- "version": "1.0.10",
3
+ "version": "1.1.0",
4
4
  "description": "Create an Acryl app: npm create acrylblends@latest",
5
5
  "license": "MIT",
6
6
  "type": "module",
@@ -36,7 +36,7 @@
36
36
  "scaffold"
37
37
  ],
38
38
  "dependencies": {
39
- "acrylblends": "^1.0.10",
39
+ "acrylblends": "^1.1.0",
40
40
  "@webboxes/app-persistence": "0.1.1"
41
41
  },
42
42
  "publishConfig": {