create-acrylblends 1.0.10 → 1.2.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.
@@ -1,108 +1,99 @@
1
- # Facilitator notes: the 90-minute ACRYL Blends workshop
1
+ # Facilitator notes: building inside the ACRYL frame
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 again for the frame: the
4
+ app is created, then **opened inside ACRYL's IDE** (projects on the left, the app's page in the canvas, files/changes/terminals on the right), a
5
+ chat model works on the app from inside the frame, and coding agents run in terminal tabs in the same folder. The data layer, the desktop window and
6
+ the panel-first flow of the previous handout are gone.
7
+
8
+ The handout is written for **acrylblends 1.2.0 or newer** (the release that carries the frame). A room on an older release is on the previous handout;
9
+ check with `npx acrylblends@latest --version` before the day.
6
10
 
7
11
  ## Before the room: put this on every machine
8
12
 
9
13
  | What | Why | How |
10
14
  | --- | --- | --- |
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` |
18
-
19
- Warm-up, once per machine (this is also the exact smoke test that the room works):
20
-
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
- ```
28
-
29
- That leaves `prepared-notes` with everything installed, including Electron.
30
-
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 |
15
+ | 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.` |
16
+ | Node.js 22.19 or newer (24 and 26 tested) | the app runs TypeScript directly | `node -v`; the app's `scripts/check-node.cjs` refuses an older Node with a clear line |
17
+ | git, and a GitHub account with `gh auth login` | the first `npm run dev` makes the folder a git repository (Files and Changes need one); the last block forks the registry | `git --version`, `gh auth status` |
18
+ | One coding agent, logged in | block 5 starts it in a terminal tab; `claude`, `codex` and `pi` all worked | `codex login` once, or run `claude` once, or pi with `DEEPSEEK_API_KEY` in the terminal that starts `npm run dev` |
19
+ | One model key | block 3 adds it in Settings > Models; without it the chat shows a connect card | a DeepSeek key from <https://platform.deepseek.com>, or a Claude/ChatGPT subscription through Sign in with an account |
20
+ | A prepared app with `npm install` done | the first install brings the frame and the chat engine (about 500 MB together); a room on one Wi-Fi should not do it 20 times | run the handout's block 1 once per machine and keep the folder as `~/acryl-workshop/prepared/` |
21
+ | A warm npm cache | the first install dominates block 1 | the prepared app does it |
22
+
23
+ **The agent setting that decides the day.** The agents are configured to act rather than describe. Check on every machine that a plain request
24
+ produces files, not a plan: ask the prepared app's chat "add a line to the app's page" and watch the Changes panel. If it only describes, the model
25
+ is waiting for permission; the handout's sentence is "do it now".
26
+
27
+ **Agent-specific checks.** Codex answering `model_not_found` means the account does not have the default model: pick one it supports (`/model` in
28
+ codex, or `model = "..."` in `~/.codex/config.toml`). pi with DeepSeek needs `DEEPSEEK_API_KEY` in the environment of the terminal that runs `npm
29
+ run dev` (the terminal tabs inherit it); the preflight reports `PASS agent pi (DeepSeek key found)`. The package is
30
+ `@earendil-works/pi-coding-agent`.
31
+
32
+ ## Timings, from the rehearsal (this Mac, packed CLI, isolated HOME)
33
+
34
+ | Minutes | Block | Measured | If late |
36
35
  | --- | --- | --- | --- |
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.
36
+ | 0-10 | preflight and setup | preflight ~15 s; the prepared app skips create and install | never cut |
37
+ | 10-20 | create and open the frame | the first `npm install` dominates (the frame and the chat engine); the frame's first page is up in a few seconds after that | use the prepared app and open its frame |
38
+ | 20-25 | the first change at /app | the Files view opens `src/routes.ts`; stop and `npm run dev` reconnects the frame in a few seconds; the page shows the edit | cut `npm test` to the take-home |
39
+ | 25-30 | Settings > Models | the key saves with Apply (`Saved DeepSeek (deepseek-official).`); the page uses it after a reload | paste the key in the first-run card instead, Save and continue |
40
+ | 30-50 | chat builds the board | the chat writes into the app folder and Changes fills; the restart loop shows it at /app/board | if the model is slow, cut the board to one column |
41
+ | 50-65 | a coding agent in a terminal | the agent tab starts in the app folder (its prompt is `my-app`); `.acryl/bin/acryl look` prints the page in the frame's tile | demo one agent and let the room follow |
42
+ | 65-80 | upgrade an older app | `npx acrylblends@latest upgrade` reports every file it changed (the `frame` line is the new layout), then `npm install` and `npm run dev` | keep the report, skip the second app |
43
+ | 80-90 | publish (take-home) | the registry check merges in about two minutes | leave it as the take-home |
44
+
45
+ What the rehearsal verified end to end on this Mac: a packed CLI in an isolated HOME, the app opened by the frame with the app's page in a tab
46
+ (the first-run tile), the Preview Notice dismissed once, Settings > Models saving a key and the chat sending with it (against a local mock), a
47
+ terminal tab running commands in the app folder, the app's page edited and shown after a restart, the door seeing the page (`acryl look`), and an
48
+ app made by the previous release upgraded and opened by the frame.
49
+
50
+ ## What to say in the room
51
+
52
+ - **The frame is the product.** The point is not "an app with a chat sidebar"; it is that ACRYL's IDE hosts the app you are building: the app is
53
+ the page in the middle, its folder is the workspace, and the agents work in that folder.
54
+ - **Settings > Models is the key's home.** The key goes to the frame's own credentials store, never the app folder or `.acrylblends` files. The
55
+ first-run card writes the same store; either path is fine.
56
+ - **The loop is stop, start, look.** A source change needs `npm run dev` again; the port is stable per app, so the frame reconnects on the same
57
+ address and the app's tab is still there. If a chat tab comes to the front after the restart, press the `my-app` tab.
58
+ - **Two kinds of agent.** The chat (DSH's own, in the frame) and the coding agents in terminal tabs are different hands on the same folder; show
59
+ both and let people pick.
60
+ - **The door.** `.acryl/bin/acryl look` prints the page with refs, `act` clicks and types. In the frame the page is the tile, and the door sees
61
+ it. This is how an agent checks its own work.
62
+ - **Production is unchanged.** The frame, the chat and the agents are development tools; `NODE_ENV=production npm start` serves the app alone.
63
+
64
+ ## Windows
65
+
66
+ Windows PowerShell 5.1 has no `&&` (two lines, or `;`); PowerShell sets variables with `$env:NAME="value"`; cmd.exe's `Ctrl-C` asks `Terminate
67
+ batch job (Y/N)?` (answer `Y`); cmd.exe does not expand `~` (use `%USERPROFILE%`). `npm install` needs the "Desktop development with C++" workload
68
+ of Visual Studio Build Tools for the terminal package; the preflight notes it.
74
69
 
75
70
  ## The no-network fallback
76
71
 
77
- If the venue has no reliable network:
78
-
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.
72
+ 1. Prepared apps with `npm install` done cover blocks 1, 2 and the frame; the models (chat and agents) still need a connection or a demo.
73
+ 2. Block 7's registry needs GitHub; if the venue is offline, publish from your machine on a hotspot at the end, or show the recording.
74
+ 3. Keep one phone hotspot for the room.
84
75
 
85
- ## Demo script for the agent block (5 minutes, if you demo instead of hands-on)
76
+ ## Demo script (five minutes, if the room is behind)
86
77
 
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/`.
78
+ 1. Prepared app, frame open on the app's page: press `+`, open **AcrylDSH Chat**, ask for a sentence on the page. Narrate the Changes panel and
79
+ the restart loop.
80
+ 2. Open a **files** tab in the right panel and show the edit the model made.
81
+ 3. `+` → **Pi** (or Claude): the agent starts in the app folder; ask it for a route; run `.acryl/bin/acryl look` in that terminal and show the
82
+ page's snapshot.
83
+ 4. Settings > Models: show where the key lives and that it is not in the app folder.
84
+ 5. Show the registry listing with an app already published.
92
85
 
93
86
  ## Resetting between sessions
94
87
 
95
- Everything a person makes lives inside their app folder and `~/acryl-workshop`. To reset a machine:
96
-
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
- ```
101
-
102
- Nothing is installed globally except the agent and Bun; neither needs cleaning between sessions.
88
+ 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
89
+ back; nothing is installed globally except the agent, `gh` and Node. An app's data lives in its `.acrylblends/` (gitignored); the model key lives in
90
+ that home's credentials store, so a fresh copy starts without it.
103
91
 
104
92
  ## What is still open
105
93
 
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.
94
+ - The frame's chat tab takes the focus when it binds its session after a restart; the app's tab is one click away and the guide says so.
95
+ - The frame's address is stable across restarts: the launcher keeps the token in the app home (owner-only, atomic) and reuses it, so an open page
96
+ comes back by reloading its URL even if the browser lost its cookie. `npx acrylblends open` prints the address of the running frame;
97
+ `npx acrylblends open --new` rotates it (the old address stops working at once and the new one is printed). The frame-side banner that names the
98
+ command is still to come (after the 120 gate work).
99
+ - The one-click WebBoxes.ai deploy and the browser-only section stay TODO(M9) until that workspace is live.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "create-acrylblends",
3
- "version": "1.0.10",
3
+ "version": "1.2.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.2.0",
40
40
  "@webboxes/app-persistence": "0.1.1"
41
41
  },
42
42
  "publishConfig": {