@imagile-dev/toil-ui 0.1.0-alpha.3 → 0.1.0-beta.2

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.
Files changed (97) hide show
  1. package/NOTICE +12 -5
  2. package/README.md +341 -41
  3. package/dist/app/assets/Graph-CS6dQALI.js +7 -0
  4. package/dist/app/assets/PowershellMan-Ic3-jSrq.css +1 -0
  5. package/dist/app/assets/PowershellMan-rG0kojOi.js +1 -0
  6. package/dist/app/assets/basket-Cj-ZPWsU.svg +73 -0
  7. package/dist/app/assets/bitter-latin-400-normal-B_gsCfHZ.woff +0 -0
  8. package/dist/app/assets/bitter-latin-400-normal-Cl9vToDR.woff2 +0 -0
  9. package/dist/app/assets/bitter-latin-600-normal-B6efaj8C.woff2 +0 -0
  10. package/dist/app/assets/bitter-latin-600-normal-Bm9hnW4x.woff +0 -0
  11. package/dist/app/assets/boot-sheet-C9B_iXU-.webp +0 -0
  12. package/dist/app/assets/chakra-petch-latin-600-normal-DQKfcdKo.woff +0 -0
  13. package/dist/app/assets/chakra-petch-latin-600-normal-DVQm9bgb.woff2 +0 -0
  14. package/dist/app/assets/chakra-petch-latin-700-normal-CnDBPjkL.woff2 +0 -0
  15. package/dist/app/assets/chakra-petch-latin-700-normal-D1s_c2du.woff +0 -0
  16. package/dist/app/assets/chakra-petch-latin-ext-600-normal-CdGvbdDU.woff2 +0 -0
  17. package/dist/app/assets/chakra-petch-latin-ext-600-normal-nL80L4xU.woff +0 -0
  18. package/dist/app/assets/chakra-petch-latin-ext-700-normal-BeviJPUl.woff +0 -0
  19. package/dist/app/assets/chakra-petch-latin-ext-700-normal-DAkvJhej.woff2 +0 -0
  20. package/dist/app/assets/chakra-petch-thai-600-normal-BiM5MXH8.woff +0 -0
  21. package/dist/app/assets/chakra-petch-thai-600-normal-C620THcd.woff2 +0 -0
  22. package/dist/app/assets/chakra-petch-thai-700-normal-B7WL5pBr.woff2 +0 -0
  23. package/dist/app/assets/chakra-petch-thai-700-normal-vZLZ_5L8.woff +0 -0
  24. package/dist/app/assets/chakra-petch-vietnamese-600-normal-Pvj4qcw_.woff +0 -0
  25. package/dist/app/assets/chakra-petch-vietnamese-600-normal-YQPWIhHU.woff2 +0 -0
  26. package/dist/app/assets/chakra-petch-vietnamese-700-normal-ZDCXY9IA.woff2 +0 -0
  27. package/dist/app/assets/chakra-petch-vietnamese-700-normal-gQuUA8Wu.woff +0 -0
  28. package/dist/app/assets/crate-loading-B9H4D652.webp +0 -0
  29. package/dist/app/assets/crate-lost-Dk5CaIuV.webp +0 -0
  30. package/dist/app/assets/dead-drop-BHoO7uon.webp +0 -0
  31. package/dist/app/assets/depot-BjEccEGj.webp +0 -0
  32. package/dist/app/assets/door-open-CL1v6qnp.svg +4 -0
  33. package/dist/app/assets/dungeon-map-Beqcufkh.webp +0 -0
  34. package/dist/app/assets/dungeon-map-T2FZ-7n0.webp +0 -0
  35. package/dist/app/assets/empty-room-BvPyqrlb.webp +0 -0
  36. package/dist/app/assets/{favicon-D8c5IAlv.svg → favicon-pNvr4nr7.svg} +5 -11
  37. package/dist/app/assets/fira-code-cyrillic-600-normal-BD56RyRT.woff +0 -0
  38. package/dist/app/assets/fira-code-cyrillic-600-normal-CPRdbepc.woff2 +0 -0
  39. package/dist/app/assets/fira-code-cyrillic-ext-600-normal-B9wE0zmr.woff2 +0 -0
  40. package/dist/app/assets/fira-code-cyrillic-ext-600-normal-DldcyWhZ.woff +0 -0
  41. package/dist/app/assets/fira-code-greek-600-normal-D_h3X2X5.woff +0 -0
  42. package/dist/app/assets/fira-code-greek-600-normal-Dxp52_By.woff2 +0 -0
  43. package/dist/app/assets/fira-code-greek-ext-600-normal-C-cQDoOk.woff +0 -0
  44. package/dist/app/assets/fira-code-greek-ext-600-normal-DtBpFRLc.woff2 +0 -0
  45. package/dist/app/assets/fira-code-latin-600-normal-BmSSHshu.woff +0 -0
  46. package/dist/app/assets/fira-code-latin-600-normal-CvYZpPHg.woff2 +0 -0
  47. package/dist/app/assets/fira-code-latin-ext-600-normal-0PFQL1eg.woff +0 -0
  48. package/dist/app/assets/fira-code-latin-ext-600-normal-Cb7jxoAi.woff2 +0 -0
  49. package/dist/app/assets/fira-code-symbols2-600-normal-Bu3RnO39.woff2 +0 -0
  50. package/dist/app/assets/fira-code-symbols2-600-normal-Dvq6IQE5.woff +0 -0
  51. package/dist/app/assets/gate-DgvMBPi9.svg +109 -0
  52. package/dist/app/assets/gauge-sheet-ZMjQ7TPd.svg +1 -0
  53. package/dist/app/assets/index-B1I248Ba.js +66 -0
  54. package/dist/app/assets/index-DNYTmC1J.css +1 -0
  55. package/dist/app/assets/jack-in-Cs60f1qu.webp +0 -0
  56. package/dist/app/assets/locked-door-CdXyTY3n.svg +4 -0
  57. package/dist/app/assets/locomotive-CPPtBzL2.webp +0 -0
  58. package/dist/app/assets/overworld-W3adxmKX.webp +0 -0
  59. package/dist/app/assets/press-start-2p-latin-400-normal-KLytu4cr.woff +0 -0
  60. package/dist/app/assets/press-start-2p-latin-400-normal-_wFEWmAB.woff2 +0 -0
  61. package/dist/app/assets/rye-latin-400-normal-CPBiwIfN.woff +0 -0
  62. package/dist/app/assets/rye-latin-400-normal-CnIDrDaJ.woff2 +0 -0
  63. package/dist/app/assets/sage-cave-Bu8KEIPH.webp +0 -0
  64. package/dist/app/assets/sensor-sheet-Dn-dKnev.svg +1 -0
  65. package/dist/app/assets/shard-sheet-NpLu-BuT.svg +101 -0
  66. package/dist/app/assets/skyline-CZ4WZ55S.webp +0 -0
  67. package/dist/app/assets/splash-Dgll39Db.webp +0 -0
  68. package/dist/app/assets/splash-hOSg5Qrh.webp +0 -0
  69. package/dist/app/assets/sprites-BUKsxG6N.webp +0 -0
  70. package/dist/app/assets/sprout-sheet-BLjjvTMl.svg +143 -0
  71. package/dist/app/assets/stone-wall-DRNYiEy2.svg +4 -0
  72. package/dist/app/assets/story-CS6l92Yr.webp +0 -0
  73. package/dist/app/assets/sun-Cyqqe255.svg +72 -0
  74. package/dist/app/assets/survey-map-BI4XT_wf.webp +0 -0
  75. package/dist/app/assets/{theme-crXsh6Dv.css → theme-63MlXwuO.css} +1 -1
  76. package/dist/app/assets/theme-BJDDePbd.css +1 -0
  77. package/dist/app/assets/theme-BVugNGOi.css +1 -0
  78. package/dist/app/assets/theme-C_ukluUB.css +1 -0
  79. package/dist/app/assets/{theme-ZdVuuddo.css → theme-D3_AOEgB.css} +1 -1
  80. package/dist/app/assets/theme-DMjUjC0D.css +1 -0
  81. package/dist/app/assets/title-1MphWZoQ.webp +0 -0
  82. package/dist/app/assets/tray-BHNdSAiO.webp +0 -0
  83. package/dist/app/assets/wanted-poster-BnjUajnc.webp +0 -0
  84. package/dist/app/assets/warp-BNB4TdQ4.webp +0 -0
  85. package/dist/app/assets/wood-CrrZEj6Y.webp +0 -0
  86. package/dist/app/index.html +3 -3
  87. package/dist/server/toil-ui.js +1823 -210
  88. package/package.json +11 -5
  89. package/dist/app/assets/Graph-By9iJybf.js +0 -7
  90. package/dist/app/assets/candle-ledger-LHVvMHKk.webp +0 -0
  91. package/dist/app/assets/crate-loading-Dw5rbPVs.webp +0 -0
  92. package/dist/app/assets/crate-lost-CaqeM6QF.webp +0 -0
  93. package/dist/app/assets/index-DqhhMfsN.js +0 -61
  94. package/dist/app/assets/index-PfJo8IRH.css +0 -1
  95. package/dist/app/assets/pallets-rO-RsztZ.webp +0 -0
  96. package/dist/app/assets/racking-BI-9puyv.webp +0 -0
  97. package/dist/app/assets/theme-CpEaUF3v.css +0 -1
package/NOTICE CHANGED
@@ -21,15 +21,22 @@ The app (dist/app/) bundles:
21
21
  (https://github.com/hafontia/Fredoka-One); each through Fontsource
22
22
  (https://fontsource.org) and licensed under the SIL Open Font License,
23
23
  Version 1.1, copied below.
24
- - For the Harvest, Starship and Realm themes, each loaded only when its theme
25
- is picked: Pixelify Sans, Copyright 2021 The Pixelify Sans Project Authors
26
- (https://github.com/eifetx/Pixelify-Sans); Orbitron, Copyright 2018 The
24
+ - For the Harvest, Starship, Realm, Sprawl, Frontier and Overworld themes, each
25
+ loaded only when its theme is picked: Pixelify Sans, Copyright 2021 The Pixelify Sans Project Authors
26
+ (https://github.com/eifetx/Pixelify-Sans); Chakra Petch, Copyright 2018 The
27
+ Chakra Petch Project Authors (https://github.com/m4rc1e/Chakra-Petch);
28
+ Orbitron, Copyright 2018 The
27
29
  Orbitron Project Authors (https://github.com/theleagueof/orbitron); Exo 2,
28
30
  Copyright 2013 The Exo 2 Project Authors
29
31
  (https://github.com/googlefonts/Exo-2.0); Grenze Gotisch, Copyright 2020 The
30
32
  Grenze Gotisch Project Authors (https://github.com/Omnibus-Type/Grenze-Gotisch);
31
- and EB Garamond, Copyright 2017 The EB Garamond Project Authors
32
- (https://github.com/octaviopardo/EBGaramond12); each through Fontsource and
33
+ EB Garamond, Copyright 2017 The EB Garamond Project Authors
34
+ (https://github.com/octaviopardo/EBGaramond12); Rye, Copyright (c) 2012,
35
+ Sorkin Type Co, with Reserved Font Name 'Rye'; and Bitter, Copyright 2011
36
+ The Bitter Project Authors (https://github.com/solmatas/BitterPro); and
37
+ Press Start 2P, Copyright 2012 The Press Start 2P Project Authors
38
+ (cody@zone38.net), with Reserved Font Name "Press Start 2P"; each through
39
+ Fontsource and
33
40
  licensed under the SIL Open Font License, Version 1.1, copied below. The
34
41
  themes' art (ui/themes/*/assets/) is original, drawn for Toil UI, and
35
42
  licensed under the Apache License, Version 2.0 with the rest of the app.
package/README.md CHANGED
@@ -5,13 +5,15 @@ A local web app for seeing work across Jira, Azure DevOps and GitHub, read throu
5
5
  with its stories, pull requests, builds and deployments side by side, a pull
6
6
  requests view for what is waiting on review, and a daily worklog of what happened.
7
7
 
8
- **Status: alpha, local only.** It runs on your own machine, binds loopback, and
8
+ **Status: beta, local only.** It runs on your own machine, binds loopback, and
9
9
  reads through toil with your own connections and dossiers, read-only. Its
10
10
  settings pages, and a dossier's name and description edited in place, are the only
11
11
  places it changes anything of toil's, and only toil's own connections and dossiers. The worklog keeps its pages and the notes you add in its own
12
12
  data folder, and writes anywhere else only when you export a page. Its Feedback dialog sends a report to Imagile through
13
13
  `toil feedback`, only when you approve it. It is a separate package from toil: installing toil
14
- never installs it.
14
+ never installs it. toil's beta commitment to stable commands, flags and output doesn't
15
+ cover Toil UI: its screens, and its server's HTTP API, which is internal to the
16
+ package, can change from one beta to the next.
15
17
 
16
18
  ## Start it
17
19
 
@@ -19,7 +21,7 @@ never installs it.
19
21
  npx @imagile-dev/toil-ui
20
22
  ```
21
23
 
22
- It needs Node 24.14 or later and installs one dependency, `@imagile-dev/toil`, at
24
+ It needs Node 24.22.1 or later on 24.x, or 26.12.1 or later, as toil does, and installs one dependency, `@imagile-dev/toil`, at
23
25
  the exact version it was built with. Until a version shows on
24
26
  [npm](https://www.npmjs.com/package/@imagile-dev/toil-ui), run it from a clone of
25
27
  the repository:
@@ -33,7 +35,7 @@ node ui/dist/server/toil-ui.js
33
35
  It prints one URL and keeps running until you press Ctrl+C:
34
36
 
35
37
  ```text
36
- Toil UI 0.1.0-alpha.1 (alpha, local only), on toil 0.1.0-alpha.3
38
+ Toil UI 0.1.0-beta.1 (beta, local only), on toil 0.1.0-beta.1
37
39
  Syncing through toil, read-only, with your own connections and dossiers. Only its Settings pages, and a dossier's name and description edited in place, change anything: toil's own connections and dossiers, when you ask. The worklog keeps its pages and your notes in its data folder, and writes anywhere else only when you export one. Feedback goes to Imagile only when you send it.
38
40
  The cache is /home/you/.toil-ui/cache/toil-ui.db, kept 30 days after each sync; toil-ui wipe deletes it.
39
41
 
@@ -50,6 +52,22 @@ itself.
50
52
  [the site's Toil UI page](https://imagile-dev.github.io/toil/ui/) runs on, with
51
53
  nothing connected to a tracker.
52
54
 
55
+ ## First run
56
+
57
+ Until you have a dossier and it has synced once, the Dossiers view shows a short
58
+ checklist in place of the empty page:
59
+
60
+ 1. **Connect a tracker** opens Settings, Connections at the add form.
61
+ 2. **Create a dossier** opens Settings, Dossiers at Create a dossier.
62
+ 3. **Sync** starts the first sync, as the Sync panel's Sync now does.
63
+
64
+ Each step ticks itself off from toil's own state: `toil connections list` for a
65
+ connection to Jira, Azure DevOps or GitHub (one made by env vars counts), `toil
66
+ dossiers list` for a dossier, and the Sync panel for the sync. Beside the steps,
67
+ **Try the sample data** shows `npx @imagile-dev/toil-ui --sample` with a Copy
68
+ button, to restart Toil UI on the sample dossiers. The checklist goes once the first
69
+ sync finishes. Each step's (i) explains it and links to these docs.
70
+
53
71
  ## What it reads
54
72
 
55
73
  Each dashboard reads its dossier the way `toil dossiers show` describes it: the
@@ -84,13 +102,13 @@ filled, plus `dossiers list` and `dossiers show` for the dossiers themselves.
84
102
  - **What this browser remembers:** when each dashboard was last opened, in
85
103
  `localStorage`, never sent anywhere. Without it (a private window) the cards just
86
104
  say nothing about "since".
87
- - **The dashboard's header** uses the same parts: the description under the name, the
88
- sources as badges, and the counts in one strip, so the panels start higher.
105
+ - **A dossier's top row** uses the same parts: the description beside the name, the
106
+ sources as badges, and the sprint's day (The dossier page, below).
89
107
 
90
108
  ### Renaming and describing a dossier
91
109
 
92
110
  The name and the description have a pencil beside them, on the card and in the
93
- dashboard's header. It opens an inline field: Enter saves through
111
+ dossier's top row. It opens an inline field: Enter saves through
94
112
  `toil dossiers describe <dossier> --name <new name>` or `--description <text>`, run
95
113
  on the settings pages' path (below), so toil's own checks apply and the change is in
96
114
  its audit log as `caller: "toil-ui"`. Escape cancels, and a refusal shows toil's
@@ -105,9 +123,122 @@ message, while a sync or an assignment of that dossier is running, since both re
105
123
  by name as they go. What can't be moved is said beside toil's result, and the next
106
124
  sync reads the dossier afresh under its new name.
107
125
 
126
+ ## The dossier page
127
+
128
+ A dossier opens on its **Overview**, in a frame all of its pages share:
129
+
130
+ - **The top row:** its name, with the pencil that renames it; **Switch**, for another
131
+ dossier or the Dossiers view; the sprint and its day; its description, cut to one
132
+ line with the whole of it in its tooltip, and its sources; and the Ask bar with
133
+ **Analyze** (The agent, below).
134
+ - **The tabs**, one address each: **Overview** (`#/dossier/<name>`), **Board**
135
+ (`/board`, with how many of its cards need attention), **Dependencies**
136
+ (`/dependencies`), **Pull requests** (`/prs`), **People** (`/people`), **Worklog**
137
+ (`/worklog`) and **Analyses** (`/analyses`). The Command Center (`/command-center`)
138
+ is the Board tab's **Readiness** view, the stand-up is the Worklog's, and an item's
139
+ page sits under Board, so every address from before the tabs still opens. On a
140
+ narrow screen the tabs scroll sideways.
141
+ - **The Agents sidebar**, beside every tab from 1200px wide, and a drawer behind the
142
+ **Agents** button below that: the tracker's inbox, then the dossier's assignments
143
+ in three groups (those that need you, those working, and those gone stale), with the
144
+ finished ones under **Earlier**; then **Renew all stale**, the **Limits**, and this
145
+ dossier's three newest analyses, each linking to it (Assigning work to an agent, below).
146
+ - **Analyses** lists every Analyze kept for the dossier, newest first: when it was made,
147
+ the adapter and model that wrote it, its one-line recommendation, and what changed
148
+ since the one before (items newly blocked or blocked by something new, blockers
149
+ cleared, points moved on an item or in the sprint, items newly cited or no longer
150
+ cited, a new recommendation). What changed is worked out by code, from a snapshot of
151
+ the dossier's items each analysis keeps, never by asking the agent. **Open** reads one
152
+ again at its own address (`/analyses/<id>`), top-down like the chat, with its
153
+ suggested changes and what it used. The server keeps them in the cache (Sync and the
154
+ cache, below), so they outlast a reload and a restart; with `--sample`,
155
+ card-payments starts with two, kept in memory for the run.
156
+
157
+ ### The Overview
158
+
159
+ The Overview puts the answer first, then the reasons, then the evidence, and fits a
160
+ 1440 by 900 screen without scrolling:
161
+
162
+ 1. **The recommendation:** the one thing to do first. When the dossier has a
163
+ current analysis (made since the data was read, or the same UTC day), it is the
164
+ latest Analyze's recommendation, with when it was made, who wrote it and a link to
165
+ it. Without one (none yet, the latest had no Recommendation line, or it is older
166
+ than the data, which the card links to), it is worked out by code from what the dossier already holds, with no agent
167
+ call (`ui/src/model/recommend.ts`), and says what it read. The card says which of
168
+ the two it is. The key issues under it are always the code's.
169
+ 2. **Three key issues**, each with its tickets as chips, every one showing its key,
170
+ title and status, and a link to the tab that has the rest.
171
+ 3. **The metrics as sparklines:** burn-up, throughput, cycle time, aging work in
172
+ progress and pull request wait, each with its figure. Pressing one opens its full
173
+ chart, with its figures in a table and what it couldn't compute.
174
+ 4. **The blockers in brief:** the critical chain as a compact Gantt on the sprint's
175
+ timeline, with its points and a link to the Dependencies tab, which has every
176
+ blocker (The Dependencies tab, below).
177
+
178
+ The key issues come from six checks, each with a fixed weight, so blockers always come
179
+ first and work not yet started comes last. Within a kind, more tickets outrank fewer.
180
+
181
+ | Issue | Raised when | Its tab |
182
+ |---|---|---|
183
+ | Blocked | An open item is blocked by another open one. The blocker holding the most, counting chains, is the one to clear first | Dependencies |
184
+ | Builds failing | An open item's latest build failed | Board |
185
+ | Points left | The sprint's pace so far (points done per working day) won't finish the points left in the days left | Board |
186
+ | Pull requests waiting | An open pull request has waited on review 2 working days or more, or its checks have failed for over a day | Pull requests |
187
+ | Aging | An item has been in progress longer than 85% of finished items took, or has had no update for more than 5 days | Board |
188
+ | Not ready | Work not started in the sprint fails the readiness gate (Readiness and the Command Center, below) | Board |
189
+
190
+ The recommendation is the heaviest issue's action. With none raised, it says to keep
191
+ going, and why.
192
+
193
+ ### The Dependencies tab
194
+
195
+ The Dependencies tab opens on the **blocker timeline**, a Gantt chart of every item that
196
+ blocks another or is blocked, on the current sprint's dates, then the dependency graph.
197
+
198
+ - **Each item is a bar.** A solid segment is its time in progress, from its
199
+ transitions. A hatched, outlined segment is its time blocked, from its `blocks`
200
+ links until the blocker finished. A thin strip under the bar is its failing checks,
201
+ from the first of its open pull requests' latest run of failed builds, or the pull
202
+ request's own failing checks. A tick after the bar means it is done, and a blocker
203
+ not started yet says so in place of a bar. Each mark
204
+ differs by its shape as well as its colour, and the key above the chart draws each
205
+ one.
206
+ - **Arrows join each blocker to what waits on it**, pointing at the item that waits.
207
+ A dashed arrow is a wait that is over: the blocker is done. A dotted line marks today.
208
+ - **The critical chain** is the chain of open blockers holding the most points (the
209
+ longest chain when nothing on any chain has points). Its rows carry a diamond and
210
+ its arrows are drawn heavy, and it is named above the chart. The Overview shows it
211
+ alone, in brief.
212
+ - **What is estimated is said, in the chart's note and on each table cell.** No tracker
213
+ toil reads dates a link, so a block is drawn from when both items existed. An item
214
+ whose history records no move into In progress (GitHub records only open and closed)
215
+ is drawn in progress from when it was created. Nothing is fetched for the chart: it
216
+ reads the links, transitions, pull requests, builds and checks the dossier already
217
+ synced, and the readiness gate's verdict for work not started.
218
+ - **The table under the chart lists every bar and every arrow**, with links: each
219
+ item's status and points, its time in progress, blocked (and by what) and with
220
+ checks failing, what it waits on, whether it is on the critical chain, and whether
221
+ it is ready to start. The chart is an image with a summary for a screen reader; the
222
+ table is its accessible equivalent, so the bars themselves aren't focusable.
223
+ - **On a narrow screen** the chart keeps its smallest width and scrolls sideways in its
224
+ own scroller, which can be focused and scrolled with the keyboard, with a line above
225
+ it saying so; the page itself never scrolls sideways.
226
+
227
+ ### The board
228
+
229
+ The Board tab flags each card that needs attention, with a flag beside its status and
230
+ an edge in the warning colour: anything that needs action now or a look (Insights,
231
+ below), but not what is only worth knowing. **Needs attention only** narrows the board
232
+ to those cards, and the tab carries how many there are. Drag a card to another column,
233
+ or press M on it for its menu, to propose the move: nothing changes until you apply
234
+ the command the proposal shows, and the card stays where its tracker says. Under the board are its
235
+ stories with their pull requests, builds and deployments, then the builds and
236
+ deployments themselves.
237
+
108
238
  ## Insights
109
239
 
110
- The dashboard's **Needs attention** panel, the board's cards and the flow panels mark
240
+ The board's cards and its **Needs attention** flag, the flow charts and the Overview's
241
+ key issues mark
111
242
  each open work item with its insights, weightiest first, each naming the data it
112
243
  rests on (`ui/src/model/insights.ts`). One the data can't support isn't raised at
113
244
  all, rather than raised on a guess.
@@ -128,8 +259,8 @@ all, rather than raised on a guess.
128
259
 
129
260
  ## Pull requests
130
261
 
131
- Each dossier has a **Pull requests** view (`#/dossier/<name>/prs`, linked from its
132
- dashboard and the header), built from OWI 0.2 changes:
262
+ Each dossier has a **Pull requests** tab (`#/dossier/<name>/prs`), built from OWI 0.2
263
+ changes:
133
264
 
134
265
  - **Waiting now:** the open pull requests, longest wait first, each with what it
135
266
  waits on (review, changes, checks, merge, or a draft its author holds), since when
@@ -153,7 +284,7 @@ repository's `owner/repo#41`). A code host's section may set author kinds by han
153
284
 
154
285
  ## People
155
286
 
156
- Each dossier has a **People** view (`#/dossier/<name>/people`, in the header), built
287
+ Each dossier has a **People** tab (`#/dossier/<name>/people`), built
157
288
  from the same OWI work items and changes as the dashboard and the pull requests view,
158
289
  and from the dossier's `people` section, which says who each person is in every
159
290
  system (`toil dossiers person`, or **Settings, Dossiers**):
@@ -162,7 +293,7 @@ system (`toil dossiers person`, or **Settings, Dossiers**):
162
293
  status with how long each item has sat in it, their open pull requests and what
163
294
  each waits on, the reviews waiting on them (oldest first), their blocked items and
164
295
  what blocks each, and what they did in the last 14 days. A link opens their items
165
- on the dashboard's board, filtered to them.
296
+ on the Board tab, filtered to them.
166
297
  - **A team strip:** work in progress against the dossier's `wipLimit` and who is over
167
298
  it, the review queue, and the current sprint's unassigned items.
168
299
  - **Agents:** a person with `kind: "agent"`, matched by the same signals as a pull
@@ -213,7 +344,7 @@ that names none uses `Microsoft.VSTS.Common.AcceptanceCriteria`.
213
344
  rows, each with where its answer came from. **Check the workflow live** makes the one
214
345
  live read, read-only: `jira issue transitions` for a Jira issue, `ado work-item
215
346
  states` for an Azure DevOps type. A GitHub issue needs none.
216
- - **The Command Center** (`#/dossier/<name>/command-center`, in the header) lists every
347
+ - **The Command Center** (`#/dossier/<name>/command-center`, the Board tab's Readiness view) lists every
217
348
  work item with its verdict and, for each one that isn't ready, the rows that say why.
218
349
  It filters by verdict, status, type, assignee and source, and makes no live read.
219
350
  It is strict: only ready items are slated, in the dossier's order, under a plan id
@@ -224,7 +355,7 @@ that names none uses `Microsoft.VSTS.Common.AcceptanceCriteria`.
224
355
  are ready for an agent?" (The agent, below).
225
356
  ## Worklog
226
357
 
227
- Each dossier has a **Worklog** (`#/dossier/<name>/worklog`, linked from the header):
358
+ Each dossier has a **Worklog** tab (`#/dossier/<name>/worklog`):
228
359
  one page a day, folded by code from what the cache holds, facts only. No model writes
229
360
  a line of it. A calendar shows the days that have a page, with how many lines each
230
361
  has; a day opens as `#/dossier/<name>/worklog/<yyyy-mm-dd>`. Days and times are UTC,
@@ -233,7 +364,8 @@ as everywhere else in Toil UI.
233
364
  A page has:
234
365
 
235
366
  - **Work items** that changed status (from, to, who and when), were added to or
236
- dropped from a sprint, or got a new blocker.
367
+ dropped from a sprint, got a new blocker or had one cleared, and each sprint that
368
+ ended, with how many of its items and points were done.
237
369
  - **Pull requests** opened, reviewed (approved, changes requested, commented), merged
238
370
  or declined.
239
371
  - **Builds and deployments** that failed or recovered (deployments from OpenShift,
@@ -253,9 +385,11 @@ Every line links to its item, pull request, build or transcript, where the sourc
253
385
  page for it. Two kinds of fact
254
386
  come in differently. Status and sprint changes, pull requests, reviews and builds
255
387
  carry their own times in the sources' history, so a page can be built for any past
256
- day the cache covers. A new blocker and a deployment that failed or came back have
257
- no time in the trackers, so a sync sees them by comparing what it read with the last
258
- sync, and the line says which sync first saw it and when the one before ran.
388
+ day the cache covers. A new blocker, a cleared one, a sprint's end and a deployment
389
+ that failed or came back have no time in the trackers, so a sync sees them by comparing
390
+ what it read with the last sync, and the line says which sync first saw it and when the
391
+ one before ran. The facts a sync records for the first time are also what play a theme's
392
+ event moments (Themes, below).
259
393
 
260
394
  **What a page can't vouch for is said at the top:** a day before the earliest sync the
261
395
  cache holds, a day no sync of a source ran on, a sync that failed, a source whose latest
@@ -363,10 +497,82 @@ it, and pressing it opens the same words with a **Read more** link to the sectio
363
497
  of these docs that says the rest. A **pencil** beside a configurable value (a
364
498
  connection, a dossier's sources, people, field names or work-in-progress limit,
365
499
  the agent, a usage cap) opens the settings page where it's set, at that value; it
366
- only navigates. **Help** in the header opens the docs for the view you're on.
367
- Read more and Help open the docs site in a new tab, which is the one place the app
368
- links out to. [Help and edit links](https://imagile-dev.github.io/toil/docs/ui-help/)
369
- has the rule views follow.
500
+ only navigates. **Help** in the header is a menu with the docs for the view you're on
501
+ and **What's new** (below).
502
+
503
+ Where a screen uses an AI term (tokens and the context window under Agent usage,
504
+ model, harness and MCP under Agent, sandbox and permission mode in the Assign
505
+ dialog's modes, session and system prompt in Renew all stale, hallucination in the
506
+ chat's **About these answers**), its (i) popover also gives each term's first
507
+ sentence from Context Overflow's glossary, with **Read more on Context Overflow**.
508
+ Help's menu then has **Learn**: four of Context Overflow's modules, by task.
509
+ The agent's empty chat has the same **Learn**. **Links to learning content**, under
510
+ **Settings, General** and kept in this browser, is on by default; off, every link to
511
+ Context Overflow and every glossary line is gone, and Help keeps the view's docs and
512
+ What's new.
513
+
514
+ Read more, Help, Learn and What's new's changelog links open in a new tab, and are the
515
+ only places the app links out to: nothing is fetched until you follow one.
516
+ [Help and edit links](https://imagile-dev.github.io/toil/docs/ui-help/) has the rule
517
+ views follow.
518
+
519
+ ### Empty panels
520
+
521
+ Every empty panel offers the one action that fills it, under one short line, with any
522
+ explanation in its (i): **Link a pipeline** and **Add an environment** (pencils to
523
+ Dossier setup at the dossier's sources) on the Board tab's builds and deployments, **Add
524
+ a repository** for pull requests, **Add a person** on the People tab, **Analyze now**
525
+ for an empty Analyses tab, **Show every item** for a Command Center filter that hides
526
+ everything, and **Sync now** in the local app wherever only a newer read of the tracker
527
+ fills the panel (the sprint, the burn-up, links between items). The site preview can't
528
+ sync, so it offers Dossier setup there instead. A test fails on any empty panel with
529
+ neither an action nor a link.
530
+
531
+ ### What's new
532
+
533
+ After an upgrade, **Help** in the header carries a dot (and so does **Menu** on a narrow
534
+ screen, which holds Help), and Help's **What's new** lists what changed in toil and Toil
535
+ UI since this browser last saw them: three to five lines a version, features first, from
536
+ each package's release notes, with a link to its full changelog. The lines are read from
537
+ `CHANGELOG.md` and `ui/CHANGELOG.md` when Toil UI is built and bundled with it, so
538
+ nothing is fetched to show them. The versions this browser last saw are kept in
539
+ `localStorage`; a first visit records them and shows no dot, and opening the list takes
540
+ the dot away. Nothing pops up over the page.
541
+
542
+ ## The command palette
543
+
544
+ **Ctrl+K** (**⌘K** on a Mac) opens the command palette from any page; on a narrow
545
+ screen it's **Search and commands** in the header's Menu. Type to narrow it down,
546
+ use the arrow keys to move, **Enter** to open and **Escape** to close. It's hidden
547
+ until you call it up.
548
+
549
+ - **Jump** to a dossier, any of a dossier's tabs (Overview, Board, Dependencies,
550
+ Pull requests, People, Worklog, Analyses), a saved analysis, a settings page, or a
551
+ theme.
552
+ - **Run** Sync now (where Toil UI keeps a cache), and on a dossier's page Ask (it
553
+ focuses the Ask bar), Analyze, the agent that answers this chat, and Assign the
554
+ item you were on to an agent: the board card that had focus, or the item whose
555
+ page is open.
556
+ - Matching is fuzzy and ignores case: `pay12` finds `PAY-12`, and each word you
557
+ type has to appear, in order. Results are grouped by kind, and the group with the
558
+ best match comes first.
559
+
560
+ ### Search across dossiers
561
+
562
+ With something typed, the palette searches the items of every dossier, by key and
563
+ title. Each result shows its dossier and status and opens the item. It reads only
564
+ what the last sync stored, never the tracker: opening it reads each dossier from
565
+ the cache the way its dashboard does. A result from a dossier last synced more than
566
+ a day ago, or whose last sync failed, says how old its copy is.
567
+
568
+ ### Keyboard shortcuts
569
+
570
+ **?** opens a sheet listing every shortcut in Toil UI, anywhere but a text field;
571
+ it's also **Keyboard shortcuts** in the palette and the header's Menu. The sheet,
572
+ the palette and the views all read one table (`src/shortcuts.ts`), and a test fails
573
+ on a key a view checks any other way, so the sheet can't fall behind. On a board
574
+ card, **M** or the Menu key opens its menu, and **Space** picks it up to move with
575
+ the arrow keys.
370
576
 
371
577
  ## Feedback
372
578
 
@@ -418,9 +624,12 @@ requests, builds and deployments that name them.
418
624
  UI runs, its write-ahead log (`toil-ui.db-wal` and `toil-ui.db-shm`) sits beside
419
625
  it, and closing folds the log back into the file. It holds
420
626
  ticket content, so it stays on this machine and is readable by your account
421
- only.
627
+ only. The analyses (#395) are kept in the same file, the newest 100 per dossier,
628
+ and a sync never rewrites them.
422
629
  - **For how long.** Anything not synced again within the retention period (30
423
- days by default) is deleted, at start and after each sync.
630
+ days by default) is deleted, at start and after each sync. An analysis goes once
631
+ it is older than the retention period, and with its dossier when toil no longer
632
+ has it.
424
633
  - **Wiping it.** **Wipe the cache** in the Sync panel deletes it after asking
425
634
  first. `toil-ui wipe` does the same from a terminal, once `toil-ui` has
426
635
  stopped: a running Toil UI holds `toil-ui.lock` in the data folder, and the
@@ -438,7 +647,7 @@ by the page: `toil audit list`, read-only, to see whether a proposal was applied
438
647
 
439
648
  ## The agent
440
649
 
441
- Every dossier page has an **Ask bar** under the header: one line, with **Analyze**
650
+ Every dossier page has an **Ask bar** in its top row: one line, with **Analyze**
442
651
  beside it. Pressing into it opens the **focused view**: the conversation takes the
443
652
  screen and the page steps back, with a slim strip that keeps the dossier, its sprint
444
653
  and the agent answering in sight. **Escape** or **Close** puts it away; the
@@ -459,7 +668,16 @@ conversation stays, for the rest of the dossier's pages, until you reload.
459
668
  (from the worklog), who is on what, what is blocked or stuck in review, the sprint's
460
669
  health and risks, and anything that looks off, such as a ticket marked done while its
461
670
  pull request is open. Every line cites its items, and follow-up questions continue
462
- from it.
671
+ from it. It answers top-down: a **Recommendation** line first, then the **Issues**
672
+ behind it (three at most), then the **Evidence**, which stays folded until you open
673
+ it. An answer that doesn't start with a Recommendation line is shown as it came, and
674
+ says so. Each whole Analyze is kept in the dossier's **Analyses** tab, and the
675
+ answer links to it.
676
+ - **Citations are chips**: in every answer, each `[[id]]` is a chip with the item's
677
+ key, title and status, linking to its page (a pull request to its host). Hovering or
678
+ focusing one shows its type, assignee, estimate, sprint and last update. An id the
679
+ dossier doesn't hold stays the bare id, marked, and the server's check above the
680
+ answer still names any id its tools never returned.
463
681
  - **Each question carries the chat so far**: its last 8 questions and answers, each
464
682
  answer cut to 1,500 characters. An item an earlier answer named is still checked
465
683
  against what the tools return for the new question.
@@ -664,9 +882,9 @@ you apply it.
664
882
  that pushes.
665
883
  - **States**: `queued` (waiting for a free slot, or for a person to press Start),
666
884
  `working`, `needs you` (proposals or questions to review, or an item the agent
667
- thought was trying to instruct it), `done` and `failed`. The **Agents** lane on the
668
- dashboard shows each assignment's state, mode, adapter, run time and what it used,
669
- and the People view shows each agent's assignments.
885
+ thought was trying to instruct it), `done` and `failed`. The **Agents** sidebar beside
886
+ every dossier tab shows each assignment's state, mode, adapter, run time and what it
887
+ used, and the People view shows each agent's assignments.
670
888
  - **From the Command Center**, "Start every ready item" assigns each slated item in
671
889
  implement mode, in order, on Codex (or the adapter chosen in Settings, when it can
672
890
  implement), in the dossier's one repository with a local path, and says what it
@@ -682,7 +900,7 @@ you apply it.
682
900
  - **Tracker text is untrusted.** The item is fenced off in the prompt as data, and an
683
901
  item that tells the agent to do anything else stops the run, marked `needs you`.
684
902
  - **Limits.** One assignment runs at a time and each has 20 minutes, both changeable
685
- in the lane's **Limits** (1 to 3 at once, 1 to 240 minutes), kept in
903
+ in the sidebar's **Limits** (1 to 3 at once, 1 to 240 minutes), kept in
686
904
  `<data folder>/assignments.json`. An assignment is one chat to the usage caps under
687
905
  **Settings, Agent usage**, so a per-chat cap is a per-assignment cap. Either limit
688
906
  stops a run cleanly, saying which.
@@ -711,14 +929,14 @@ started on, says which have gone stale and why, and renews them on request.
711
929
  prompt, the starters or the mode's task, and your own instructions and voice). The
712
930
  theme on screen isn't part of it. An assignment recorded before this has none, and
713
931
  is never called stale.
714
- - **When it's stale.** Every answer, every read of the Agents lane and every
932
+ - **When it's stale.** Every answer, every read of the Agents sidebar and every
715
933
  assignment page compares what the session started on with the current fingerprint,
716
934
  whose builds are the ones on disk, read again only when their files change. The
717
935
  reason names what moved: "started on toil 0.1.0-alpha.3 · now alpha.4 · skills
718
936
  changed: github · dossier changed". A session's earlier turns aren't marked; only
719
937
  the instructions it started on are.
720
938
  - **Where it shows.** A **Stale** badge with the reason on the chat (in the Ask bar and
721
- the focused view), on each assignment in the Agents lane and on its page, and on the
939
+ the focused view), on each assignment in the Agents sidebar and on its page, and on the
722
940
  agent's card in the People view. A done assignment is closed and isn't marked.
723
941
  - **Renew.** On the chat, **Renew** in the focused view records what it starts on now;
724
942
  the conversation stays, and the next question carries it as every question does. The
@@ -728,7 +946,7 @@ started on, says which have gone stale and why, and renews them on request.
728
946
  stays readable, marked as renewed. Renew never interrupts a turn: a chat that is
729
947
  answering and a working assignment wait, and an assignment that needs you is
730
948
  skipped until you've reviewed it.
731
- - **Renew all stale**, in the Agents lane, lists every stale session of the dossier
949
+ - **Renew all stale**, in the Agents sidebar, lists every stale session of the dossier
732
950
  first, the chat included, each saying whether it renews or why it's skipped, and
733
951
  renews the rest with one press.
734
952
  - **The server itself.** When toil or Toil UI on disk is newer than the running
@@ -764,9 +982,23 @@ call, its progress, or a state that didn't change never notifies.
764
982
  which carries what a notice says with each event, and a minute's read of the
765
983
  dossier on screen for sessions gone stale.
766
984
 
985
+ ### Notification history
986
+
987
+ The **bell** in the header (beside **Menu** on a narrow screen) counts the unread and
988
+ opens the last 50 things worth telling you, newest first: each change a notice carried
989
+ (needs you, done, failed, stopped at a usage cap, gone stale), each sync's result, from
990
+ the Sync panel, with the dossier that failed, and when each happened. Every entry links
991
+ to what it's about: the assignment, the dossier, or the Dossiers view. **Mark all read**
992
+ clears the count and keeps the entries. The bell keeps a change that quiet hours held
993
+ back, and one whose notice you dismissed; which changes reach it is the notification
994
+ settings' choice. It's kept in this browser's `localStorage`, shared by its tabs (with one
995
+ entry for each event, however many tabs saw it), and sent nowhere. Notices follow the rules above unchanged, and a theme's moments play from
996
+ the worklog's facts, never from the bell.
997
+
767
998
  ## Themes
768
999
 
769
- Five built-in themes: Plain, Crate (the default), Harvest, Starship and Realm. Pick
1000
+ Eight built-in themes: Plain, Crate (the default), Harvest, Starship, Realm, Sprawl,
1001
+ Frontier and Overworld. Pick
770
1002
  one from the header, or under **Settings, General**, where two checkboxes say how far
771
1003
  it goes, both on by default:
772
1004
 
@@ -776,16 +1008,29 @@ it goes, both on by default:
776
1008
  read the same in every theme.
777
1009
  - **Themed agent voice:** the agent answers in the theme's register, a terse
778
1010
  dockworker in Crate, a patient farmhand in Harvest, a ship's log in Starship, a
779
- house's steward in Realm. It changes phrasing only.
1011
+ dungeon master in Realm, a laconic netrunner in Sprawl, a dry telegraph operator
1012
+ in Frontier, an old sage in a cave in Overworld. It changes phrasing only.
780
1013
 
781
1014
  A theme with particles also gets **Particles and ambient effects**, kept for each
782
1015
  theme on its own: off, that theme's particles are gone entirely, while its other
783
1016
  motion keeps following **Reduce motion and effects** (and the operating system's
784
1017
  reduced-motion setting, which stops everything).
785
1018
 
1019
+ Crate, Harvest, Starship, Realm, Sprawl, Frontier and Overworld also have **theme moments**: a launch splash while the first read
1020
+ runs, their own loading screens with the real progress and a rotating line of their own,
1021
+ an entrance as a dossier opens, a transition between its tabs, and a short moment when a
1022
+ sync brings an item done, a build passed or failed, a blocker cleared, a pull request
1023
+ merged, or a sprint's end. **Theme motion**, under Settings, General, plays them in full,
1024
+ subtly or not at all, and is off whenever reduced motion is asked for. Every loading
1025
+ screen also carries a **toil tip**, one line with a Read more link, which **Toil tips on
1026
+ loading screens** turns off. Waits under 300 ms show no loading screen at all.
1027
+
786
1028
  Plain has neither wording nor voice, so both are off while it's chosen. It sets
787
- headings and figures in Fredoka, toil's wordmark face, on IBM Plex Sans. The choice
788
- is kept in this browser. Toil UI doesn't install themes from anywhere else: to ask for one, send a
1029
+ headings and figures in Fredoka, toil's wordmark face, on IBM Plex Sans. The theme
1030
+ is toil's own setting too (`toil theme set`, `TOIL_THEME` over it), which the welcome
1031
+ menu follows: a pick here writes it, and Toil UI opens in it, except in a browser that
1032
+ had a theme saved before the setting, which keeps it until the next pick. The other
1033
+ choices are kept in this browser. Toil UI doesn't install themes from anywhere else: to ask for one, send a
789
1034
  feature request from **Feedback** or with `toil feedback feature`. A `themes/` folder
790
1035
  left in the data folder by an earlier alpha is not read, and Toil UI says so when it
791
1036
  starts. [Themes](https://imagile-dev.github.io/toil/docs/themes/) has the whole
@@ -891,11 +1136,17 @@ npm run verify:ui -- --no-build --starter standup
891
1136
  is what the published package runs on.
892
1137
  - **Sample data:** `toil-ui --sample` in a throwaway home, every view through the
893
1138
  layout check (`scripts/layout-check.mjs`) in every theme and scheme at 375, 768 and
894
- 1440px. It needs only a browser, so it runs anywhere, CI included.
1139
+ 1440px. On each dossier's dashboard it also drags a board card to the next column
1140
+ with real input, a mouse and at 375px a finger, and fails when the card doesn't
1141
+ follow the pointer or the dropped move doesn't show in the target column. It needs
1142
+ only a browser, so it runs anywhere, CI included.
1143
+ - **First run:** `toil-ui` on an empty home, with no connections, no dossiers and no
1144
+ `TOIL_*` variable from your shell, through the same check: its Dossiers view must
1145
+ show the three-step checklist, and the palette and the shortcuts sheet open over it.
895
1146
  - **Real data:** the home `dev-real.mjs` sets up, made fresh at
896
1147
  `.scratch/verify/home`, on `imagile-dev/toil-sandbox` with the token from `gh auth
897
1148
  token` in Toil UI's environment only. It syncs the `sandbox` dossier and runs the
898
- same check over the home page, the dossier, one of its items and the settings pages,
1149
+ same check over the home page, the dossier and its Board and Dependencies tabs, its worklog and stand-up, one of its items and the settings pages,
899
1150
  except that its header may fold into the Menu at 1440px, since a real dossier's name
900
1151
  and links can genuinely fill the row.
901
1152
  Without a GitHub sign-in it skips this part and says so; nothing else depends on it.
@@ -903,7 +1154,12 @@ npm run verify:ui -- --no-build --starter standup
903
1154
  checks that an answer arrived, that the server verified every `[[id]]` it cites,
904
1155
  that its proposals parsed, that nothing ran (no write in toil's audit log for the
905
1156
  run), and that `codex mcp list` in Toil UI's Codex home shows only `toil_ui`. Then it
906
- asks Analyze as the chat's second question. It needs the Codex CLI signed in and the
1157
+ asks Analyze as the chat's second question, and checks the history of analyses
1158
+ (#395): that Analyze was kept, top-down (a Recommendation line, three issues at
1159
+ most); then it changes the dossier's WIP limit in the scratch home (`toil dossiers
1160
+ wip-limit --replace`), asks Analyze again, checks the history lists both, newest
1161
+ first, the second compared with the first, and puts the Overview, the Analyses tab
1162
+ and the second analysis opened through the layout check, shot. It needs the Codex CLI signed in and the
907
1163
  SDK installed in the clone (above). `--adapter copilot` or `--adapter claude` asks that
908
1164
  adapter instead, held to the same checks (Codex is the reference; its MCP check is
909
1165
  skipped), and `--model <id>` sets its model and fails the run when an answer or a
@@ -1000,6 +1256,50 @@ toil util owi map board.jsonl > mapped.json
1000
1256
  node ui/scripts/ado-seed/compare.mjs mapped.json --project "<project>" --backdated
1001
1257
  ```
1002
1258
 
1259
+ ## Measuring theme moments
1260
+
1261
+ Two more commands are for a PR that changes a theme's moments ([Theme
1262
+ moments](https://imagile-dev.github.io/toil/docs/themes/#theme-moments)) or the engine that
1263
+ plays them. Both build Toil UI first (`--no-build` skips it), run `toil-ui --sample` in a
1264
+ throwaway home, drive headless Chrome (the one the layout check finds; `CHROME_PATH` picks
1265
+ another), and write to `ui/.moments/`, which git ignores.
1266
+
1267
+ ```bash
1268
+ npm run moments:measure -w ui # every theme with moments, 3 runs each
1269
+ npm run moments:measure -w ui -- --theme realm --cold
1270
+ npm run screens:sheet -w ui # every theme, 375 and 1440px, full, subtle and off
1271
+ npm run screens:sheet -w ui -- --theme realm --width 768 --motion full
1272
+ ```
1273
+
1274
+ - **`moments:measure`** times each theme's launch splash, loading screen and sprint recap at
1275
+ 1440px with GPU compositing on. A `requestAnimationFrame` recorder gives the frame times
1276
+ (Sprawl's rain and Realm's embers draw at 30 fps by design, which raw presented-frame gaps
1277
+ would misread), and Chrome's frame reporter the frames it dropped. Each run opens a fresh
1278
+ browser per theme and plays it twice: the first pass is Chrome compiling its GPU shaders,
1279
+ which a person sees at most once per browser version, and the second is the figure. It
1280
+ prints a table, each cell the median frame, the worst frame, the frames over 20 ms and the
1281
+ frames Chrome dropped over every run, and writes it to `ui/.moments/measure.md` with the
1282
+ raw results in `measure.json` beside it. It exits 1 when any frame is over 20 ms or a phase
1283
+ didn't play. `--report-only` prints the same and exits 0; `--cold` adds the first pass's
1284
+ worst frames; `--runs <n>` (default 3), `--motion subtle`, `--throttle <rate>` (a slower
1285
+ CPU) and `--no-gpu` (software rendering) change the run. It takes about two minutes a
1286
+ theme.
1287
+ - **`screens:sheet`** makes one contact sheet for each theme, width and Theme motion level,
1288
+ `ui/.moments/sheets/<theme>-<width>-<motion>.png`, ready to attach to the PR, with its
1289
+ frames and an HTML copy in a folder beside it. A sheet shows the splash arriving, held and
1290
+ handing over; the loading screen as its loops turn; each event moment the theme declares
1291
+ coming in, held and going out, cropped to the card; the dossier entrance; and a change of
1292
+ tab. Every frame is a still: the engine's animations are caught paused as they start and
1293
+ stepped by hand, so a sheet is the same on every run. `--width` and `--motion` repeat, and
1294
+ replace the defaults.
1295
+
1296
+ **Run them on a quiet machine, with nothing else running**: no build, no other test run, no
1297
+ video call. A frame time measures the machine as much as the page, so a busy machine's slow
1298
+ frames aren't the theme's. `moments:measure` reads the CPU before it starts, says so when the
1299
+ machine is already more than 15% busy, and puts both readings, before and during, at the top of
1300
+ its table. For the same reason neither command runs in CI, and neither is part of
1301
+ `npm run verify:ui`. Put the table and the sheets in the PR, with the load the run saw.
1302
+
1003
1303
  ## Settings
1004
1304
 
1005
1305
  | Setting | Flag | Env var | Default |
@@ -1015,7 +1315,7 @@ release. The data folder is Toil UI's own, apart from toil's `~/.toil/`, and hol
1015
1315
  the cache, `agent.json` and `usage.json`. A `~` at the start of `TOIL_UI_DATA_DIR` means your home folder, on
1016
1316
  Windows too.
1017
1317
 
1018
- ## Not in this alpha
1318
+ ## Not in this beta
1019
1319
 
1020
1320
  - **Serving other machines.** It is local only.
1021
1321
  - **Implement mode on Claude or Copilot**, and **answering an agent's questions in the assignment** itself: answer on the item and assign it again.