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

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 (40) hide show
  1. package/NOTICE +4 -6
  2. package/README.md +821 -29
  3. package/dist/app/assets/Graph-By9iJybf.js +7 -0
  4. package/dist/app/assets/candle-ledger-LHVvMHKk.webp +0 -0
  5. package/dist/app/assets/favicon-D8c5IAlv.svg +16 -0
  6. package/dist/app/assets/fredoka-latin-ext-600-normal-BExgZzUO.woff +0 -0
  7. package/dist/app/assets/fredoka-latin-ext-600-normal-GoyidTAB.woff2 +0 -0
  8. package/dist/app/assets/grenze-gotisch-latin-600-normal-C3H1tCTC.woff2 +0 -0
  9. package/dist/app/assets/grenze-gotisch-latin-600-normal-DwyVc51H.woff +0 -0
  10. package/dist/app/assets/grenze-gotisch-latin-800-normal-BIIxJnpI.woff2 +0 -0
  11. package/dist/app/assets/grenze-gotisch-latin-800-normal-DByO6Q7M.woff +0 -0
  12. package/dist/app/assets/index-DqhhMfsN.js +61 -0
  13. package/dist/app/assets/index-PfJo8IRH.css +1 -0
  14. package/dist/app/assets/mark-bSC__Aar.svg +188 -0
  15. package/dist/app/assets/theme-CpEaUF3v.css +1 -0
  16. package/dist/app/assets/theme-ZdVuuddo.css +1 -0
  17. package/dist/app/assets/theme-crXsh6Dv.css +1 -0
  18. package/dist/app/assets/vellum-DlU0Uxzz.webp +0 -0
  19. package/dist/app/assets/war-map-_sup_aJg.webp +0 -0
  20. package/dist/app/index.html +3 -3
  21. package/dist/server/toil-ui.js +18806 -6481
  22. package/package.json +6 -5
  23. package/dist/app/assets/Graph-IKubvexT.js +0 -7
  24. package/dist/app/assets/cinzel-decorative-latin-700-normal-CnX1aK6s.woff2 +0 -0
  25. package/dist/app/assets/cinzel-decorative-latin-700-normal-ov6XPGpn.woff +0 -0
  26. package/dist/app/assets/cinzel-decorative-latin-ext-700-normal-BaOC-94C.woff +0 -0
  27. package/dist/app/assets/cinzel-decorative-latin-ext-700-normal-Dul5pKgq.woff2 +0 -0
  28. package/dist/app/assets/cinzel-latin-600-normal-CH_LB4su.woff +0 -0
  29. package/dist/app/assets/cinzel-latin-600-normal-Dd5YO2UX.woff2 +0 -0
  30. package/dist/app/assets/cinzel-latin-ext-600-normal-BEFdM_VE.woff2 +0 -0
  31. package/dist/app/assets/cinzel-latin-ext-600-normal-BY9Mq9iK.woff +0 -0
  32. package/dist/app/assets/favicon-Btr9J4ll.svg +0 -18
  33. package/dist/app/assets/index-2965QO04.js +0 -28
  34. package/dist/app/assets/index-DafJtVDX.css +0 -1
  35. package/dist/app/assets/map-CFr4oRAS.webp +0 -0
  36. package/dist/app/assets/parchment-B0DDSYQX.webp +0 -0
  37. package/dist/app/assets/quill-and-scroll-BTgvJtxg.webp +0 -0
  38. package/dist/app/assets/theme-B5wzykBQ.css +0 -1
  39. package/dist/app/assets/theme-CHdX0u8s.css +0 -1
  40. package/dist/app/assets/theme-DivLOVED.css +0 -1
package/README.md CHANGED
@@ -2,12 +2,14 @@
2
2
 
3
3
  A local web app for seeing work across Jira, Azure DevOps and GitHub, read through
4
4
  [toil](https://www.npmjs.com/package/@imagile-dev/toil): one dashboard per dossier,
5
- with its stories, pull requests, builds and deployments side by side.
5
+ with its stories, pull requests, builds and deployments side by side, a pull
6
+ requests view for what is waiting on review, and a daily worklog of what happened.
6
7
 
7
8
  **Status: alpha, local only.** It runs on your own machine, binds loopback, and
8
9
  reads through toil with your own connections and dossiers, read-only. Its
9
- settings pages are the one place it changes anything, and only toil's own
10
- connections and dossiers. Its Feedback dialog sends a report to Imagile through
10
+ settings pages, and a dossier's name and description edited in place, are the only
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
+ data folder, and writes anywhere else only when you export a page. Its Feedback dialog sends a report to Imagile through
11
13
  `toil feedback`, only when you approve it. It is a separate package from toil: installing toil
12
14
  never installs it.
13
15
 
@@ -32,7 +34,7 @@ It prints one URL and keeps running until you press Ctrl+C:
32
34
 
33
35
  ```text
34
36
  Toil UI 0.1.0-alpha.1 (alpha, local only), on toil 0.1.0-alpha.3
35
- Syncing through toil, read-only, with your own connections and dossiers. Only its Settings pages change anything: toil's own connections and dossiers, when you ask. Feedback goes to Imagile only when you send it.
37
+ 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.
36
38
  The cache is /home/you/.toil-ui/cache/toil-ui.db, kept 30 days after each sync; toil-ui wipe deletes it.
37
39
 
38
40
  Open this URL in your browser. It carries this launch's token, so keep it to yourself:
@@ -44,18 +46,280 @@ token leaves the address bar. A reloaded page forgets its session, so open the U
44
46
  again to get back in. Each start prints a new token. Toil UI opens no browser
45
47
  itself.
46
48
 
47
- `toil-ui --sample` serves the sample dossiers and the scripted agent the site's
48
- preview uses, with nothing connected to a tracker.
49
+ `toil-ui --sample` serves the sample dossiers and the scripted agent that
50
+ [the site's Toil UI page](https://imagile-dev.github.io/toil/ui/) runs on, with
51
+ nothing connected to a tracker.
49
52
 
50
53
  ## What it reads
51
54
 
52
55
  Each dashboard reads its dossier the way `toil dossiers show` describes it: the
53
56
  Jira project, the Azure DevOps project and pipelines, the GitHub repository and
54
- project board, and the OpenShift namespace of each environment. Every call runs
57
+ project board, and the OpenShift namespace of each environment. A GitHub section
58
+ with no `projects` reads the repository's own issues, open and closed, as its work
59
+ items, with the history of every open one and the 50 most recently closed. Pull
60
+ requests are read from every code host the dossier names (GitHub, Bitbucket Data
61
+ Center and Cloud, Azure DevOps Server and Services) with `pr list`, then `pr get
62
+ --include reviews,checks,commits,files` for every open one and the 20 newest closed or
63
+ merged ones, and mapped to OWI 0.2 changes; a GitHub repository's CODEOWNERS is read
64
+ with `github repo file` when an open pull request has no reviewer. Every call runs
55
65
  in-process through `@imagile-dev/toil/api`, read-only, and toil's audit log
56
66
  records it with `via: "api"` and `caller: "toil-ui"`. A call that fails shows on
57
67
  its own panel with toil's message and fix.
58
68
 
69
+ ## The Dossiers view
70
+
71
+ Toil UI opens on its dossiers, one card each, read from the same data the dashboards
72
+ read, so it asks no tracker anything: in the local app that is the cache a sync
73
+ filled, plus `dossiers list` and `dossiers show` for the dossiers themselves.
74
+
75
+ - **What each card shows:** the current sprint with its working days left, points
76
+ done and a small burn-up; how many items are in progress and blocked, and how many
77
+ pull requests wait on a review; the people with work in it, as avatars; its sources
78
+ as badges; when it was last synced; and how many work items and pull requests
79
+ changed since this browser last opened its dashboard.
80
+ - **Which card leads:** the dossier opened most recently in this browser, or, before
81
+ any was opened, the one with the most in motion (in progress, blocked and waiting on
82
+ review together), takes two columns where they fit. On a wide screen the grid goes
83
+ wider than the dashboards and fits more cards across; at 375px it is one column.
84
+ - **What this browser remembers:** when each dashboard was last opened, in
85
+ `localStorage`, never sent anywhere. Without it (a private window) the cards just
86
+ 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.
89
+
90
+ ### Renaming and describing a dossier
91
+
92
+ 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
94
+ `toil dossiers describe <dossier> --name <new name>` or `--description <text>`, run
95
+ on the settings pages' path (below), so toil's own checks apply and the change is in
96
+ its audit log as `caller: "toil-ui"`. Escape cancels, and a refusal shows toil's
97
+ message and fix under the field. Only a dossier in your own folder can be renamed or
98
+ described; a checked-in one is refused with the `toil dossiers import` fix.
99
+
100
+ A rename keeps everything Toil UI holds for the dossier: the server moves its cache
101
+ (responses, items, history, sources, sync runs, notes and agent runs), its assignments
102
+ and its worklog pages to the new name once toil has renamed the file, so its
103
+ dashboard opens straight away with no new sync. A rename waits, refused with a
104
+ message, while a sync or an assignment of that dossier is running, since both read it
105
+ by name as they go. What can't be moved is said beside toil's result, and the next
106
+ sync reads the dossier afresh under its new name.
107
+
108
+ ## Insights
109
+
110
+ The dashboard's **Needs attention** panel, the board's cards and the flow panels mark
111
+ each open work item with its insights, weightiest first, each naming the data it
112
+ rests on (`ui/src/model/insights.ts`). One the data can't support isn't raised at
113
+ all, rather than raised on a guess.
114
+
115
+ | Insight | Means | Weight |
116
+ |---|---|---|
117
+ | Blocked | Another item that isn't done blocks it (its links) | needs action now |
118
+ | Build failing | Its pull request's latest build failed | needs action now |
119
+ | Aging | In progress longer than 85% of the dossier's finished items took; needs at least three cycle times to compare with | needs action now |
120
+ | Deployed, still open | An environment runs it, but it isn't done | needs a look |
121
+ | Carried over | It was in the previous sprint too | needs a look |
122
+ | PR with no build | A pull request for it is open with no build | needs a look |
123
+ | Stale | No update for more than 5 days | needs a look |
124
+ | Blocking | It blocks another item | needs a look |
125
+ | Merged, not deployed | Its pull requests are merged, but no environment runs them yet; only for a dossier that names environments | worth knowing |
126
+ | No estimate | It has no estimate | worth knowing |
127
+ | Added mid-sprint | It joined the sprint after it started | worth knowing |
128
+
129
+ ## Pull requests
130
+
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:
133
+
134
+ - **Waiting now:** the open pull requests, longest wait first, each with what it
135
+ waits on (review, changes, checks, merge, or a draft its author holds), since when
136
+ in working days and why, who wrote it (a person, an agent or a bot, with the signal
137
+ that said so), the work items it names, and its size, XS to XL by changed lines.
138
+ - **Flags:** no first review in 2 working days, checks failing for over a day, a merge
139
+ conflict, no linked work item, a work item done while its pull request is open, and
140
+ a merged pull request whose item isn't done, each with what it rests on.
141
+ - **Flow:** pickup (opened to first review), review (first review to approval) and
142
+ merge (approval to merge) times, review rounds, sizes and merges per week, over six
143
+ weeks, each split by people, agents and bots and each with its sample size and what
144
+ couldn't be measured.
145
+ - **Suggested reviewers:** for an open pull request with nobody asked, the CODEOWNERS
146
+ of its paths and the earlier reviewers of the same files and folders, each as a
147
+ proposal with the `toil … --allow-write` line to ask them.
148
+
149
+ The dossier's work item keys are matched in each pull request's title, branch and
150
+ description (a Jira project's `PAY-101`, Azure Boards' `AB#2302`, a GitHub
151
+ repository's `owner/repo#41`). A code host's section may set author kinds by hand,
152
+ `"authorKinds": { "release-bot": "BOT" }`, which win over every other signal.
153
+
154
+ ## People
155
+
156
+ Each dossier has a **People** view (`#/dossier/<name>/people`, in the header), built
157
+ from the same OWI work items and changes as the dashboard and the pull requests view,
158
+ and from the dossier's `people` section, which says who each person is in every
159
+ system (`toil dossiers person`, or **Settings, Dossiers**):
160
+
161
+ - **A card per person**, agents included, in name order: their work in progress by
162
+ status with how long each item has sat in it, their open pull requests and what
163
+ each waits on, the reviews waiting on them (oldest first), their blocked items and
164
+ 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.
166
+ - **A team strip:** work in progress against the dossier's `wipLimit` and who is over
167
+ it, the review queue, and the current sprint's unassigned items.
168
+ - **Agents:** a person with `kind: "agent"`, matched by the same signals as a pull
169
+ request's author kind (its account, a Co-Authored-By trailer, a branch prefix) where
170
+ the signal names it. A person's own pull request written with an agent says so.
171
+ - **Accounts the dossier doesn't map** get cards of their own, so no work goes
172
+ missing. One that shares an email with a person, or with an account in another
173
+ system, is suggested as a match with the `toil dossiers person` line that applies
174
+ it; it is applied only when someone presses the button, and an email that fits more
175
+ than one candidate suggests nothing and says why. Accounts that only wrote bots'
176
+ pull requests are left out and counted.
177
+
178
+ It shows what is on each plate and never scores anyone: no ranking, no productivity
179
+ figure, no person-to-person comparison and no line or commit counts. Flow metrics
180
+ stay team-level, in the pull requests view.
181
+
182
+ ## Readiness and the Command Center
183
+
184
+ Before a work item goes to an agent, Toil UI checks whether it is ready for one. The
185
+ check uses no model and no premium request: only the item's cached OWI record, the
186
+ dossier's other items, and at most one live read, made when you press for it
187
+ (`ui/src/model/readiness.ts`). Its verdict is **ready**, **thin** or **blocked**, with
188
+ one row per check:
189
+
190
+ | Check | Passes when | Otherwise |
191
+ |---|---|---|
192
+ | Acceptance criteria | The field the dossier names has them, or the description has an "Acceptance criteria", "Definition of done" or "Done when" heading with text under it, or a checklist | thin |
193
+ | Description | At least `minWords` words (25 by default) of real text, not counting the dossier's template lines, placeholder lines (TBD, N/A, lorem ipsum) or unfilled `<slots>` | thin |
194
+ | Done state | It isn't done, and a way to Done is known: a GitHub issue closes from any state; otherwise an item of the same type in the dossier reached Done, or the live read finds a Done state (Azure DevOps) or a move into Done (Jira) | blocked when it's already done, or the workflow has no Done state; thin when it isn't known |
195
+ | Blockers | No open item blocks it | blocked by an open item; thin for a blocker the dossier doesn't hold |
196
+ | Scope | It comes from one of the dossier's sources, and the dossier names a repository | blocked from outside the dossier; thin with no repository |
197
+
198
+ The verdict is blocked when any row is, thin when any row is, and ready only when every
199
+ row passes. Each area's section in the dossier sets it up:
200
+
201
+ ```json
202
+ "jira": {
203
+ "project": "PAY",
204
+ "fields": { "acceptanceCriteria": "customfield_10500" },
205
+ "readiness": { "minWords": 20, "templates": ["## What\n## Why\n## Acceptance criteria"] }
206
+ }
207
+ ```
208
+
209
+ `fields.acceptanceCriteria` is also the area's `--field` alias. An Azure DevOps section
210
+ that names none uses `Microsoft.VSTS.Common.AcceptanceCriteria`.
211
+
212
+ - **On each item's page**, a **Ready for an agent?** panel shows the verdict and its
213
+ rows, each with where its answer came from. **Check the workflow live** makes the one
214
+ live read, read-only: `jira issue transitions` for a Jira issue, `ado work-item
215
+ states` for an Azure DevOps type. A GitHub issue needs none.
216
+ - **The Command Center** (`#/dossier/<name>/command-center`, in the header) lists every
217
+ work item with its verdict and, for each one that isn't ready, the rows that say why.
218
+ It filters by verdict, status, type, assignee and source, and makes no live read.
219
+ It is strict: only ready items are slated, in the dossier's order, under a plan id
220
+ that changes when anything in the plan does.
221
+ - **Starting the plan comes with assign-to-agent (#293).** Until then the start button
222
+ is disabled and says so; the plan it would start is shown above it.
223
+ - **The agent** gets `readiness_list` and `readiness_get` and a starter, "Which items
224
+ are ready for an agent?" (The agent, below).
225
+ ## Worklog
226
+
227
+ Each dossier has a **Worklog** (`#/dossier/<name>/worklog`, linked from the header):
228
+ one page a day, folded by code from what the cache holds, facts only. No model writes
229
+ a line of it. A calendar shows the days that have a page, with how many lines each
230
+ has; a day opens as `#/dossier/<name>/worklog/<yyyy-mm-dd>`. Days and times are UTC,
231
+ as everywhere else in Toil UI.
232
+
233
+ A page has:
234
+
235
+ - **Work items** that changed status (from, to, who and when), were added to or
236
+ dropped from a sprint, or got a new blocker.
237
+ - **Pull requests** opened, reviewed (approved, changes requested, commented), merged
238
+ or declined.
239
+ - **Builds and deployments** that failed or recovered (deployments from OpenShift,
240
+ whose state a sync can see change): a build is recovered when a
241
+ passing run follows a failing one of the same pull request or pipeline.
242
+ - **Agent runs:** each question an agent adapter answers in the chat, when it
243
+ started and ended,
244
+ whether it finished, failed, was stopped or was stopped at a usage cap, what it
245
+ cited, and its proposals, each
246
+ with whether toil's audit log (`toil audit list`) shows a person ran that write on
247
+ the same item afterwards. Each run's transcript is kept beside the pages and shown
248
+ under the run, labelled as the agent's.
249
+ - **Notes** a person added that day, on today's page.
250
+ - **Sources:** each source's syncs that day.
251
+
252
+ Every line links to its item, pull request, build or transcript, where the source has a
253
+ page for it. Two kinds of fact
254
+ come in differently. Status and sprint changes, pull requests, reviews and builds
255
+ 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.
259
+
260
+ **What a page can't vouch for is said at the top:** a day before the earliest sync the
261
+ cache holds, a day no sync of a source ran on, a sync that failed, a source whose latest
262
+ sync failed, today so far, and a day older than the retention period.
263
+
264
+ **How it's kept.** Each sync records its facts in the cache, one row per fact by a key
265
+ that never changes, so the same fact synced twice is one row. After each sync every
266
+ page is folded again from the cache and written where its text changed, as Markdown
267
+ in the data folder:
268
+
269
+ ```text
270
+ <data folder>/cache/worklog/<dossier>/<yyyy-mm>/<yyyy-mm-dd>.md
271
+ <data folder>/cache/worklog/<dossier>/runs/<run id>.md
272
+ ```
273
+
274
+ The pages live under the cache's retention: a day whose rows are gone loses its page,
275
+ and a wipe deletes them all. **Rebuild this day** folds the day again and says whether
276
+ it came out the same as the page kept; the same cache always gives the same page.
277
+
278
+ **Export** writes the day's or the month's Markdown into a folder you name, through
279
+ toil's own file service: `toil util encode base64 --decode --out <file>`, run with that
280
+ folder as its workspace, which writes a new file only and never into toil's own
281
+ config. Publishing an exported page is a proposal: `toil confluence page create
282
+ --body-file <file> --markdown` in the dossier's Confluence space, or `toil github issue
283
+ create --body-file <file>` in its repository, for you to run through toil's write gate.
284
+ Toil UI posts nothing. With sample data, notes and export are off.
285
+
286
+ ### Stand-up
287
+
288
+ **Stand-up since the last working day**, on the Worklog
289
+ (`#/dossier/<name>/worklog/standup`), reshapes the worklog for a meeting: since the last
290
+ working day through today (Friday through Monday on a Monday), or any range of up to 31
291
+ days you pick (`#/dossier/<name>/worklog/standup/<from>/<to>`, or `/<day>` for one), and each day's page has a
292
+ **Stand-up for this day**. It is a fold of those days' pages by code, with no model, so the
293
+ same days always give the same report.
294
+
295
+ - **Team lines first:** the sprint's working days left, items added to or dropped from a
296
+ sprint, and builds and deployments that broke or recovered.
297
+ - **Then each person, agents included,** in four lists: **Done** (items moved into a done
298
+ status, pull requests merged or closed), **In progress** (every other status change,
299
+ pull requests opened or reviewed), **Blocked** (a new blocker on an item they hold, a
300
+ failed build of their pull request, a pull request of theirs waiting on review for 2
301
+ working days or more) and **Next** (current-sprint items assigned to them and not
302
+ started). A line belongs to whoever the fact names: who moved the item, who wrote or
303
+ reviewed the pull request. A pull request a dossier agent wrote goes under the agent.
304
+ - **People** come from the dossier's `people`, so one person's Jira, Azure DevOps and
305
+ GitHub accounts land under one name. An account the dossier doesn't map gets its own
306
+ card, named with its area and id; the People view suggests where it belongs.
307
+ - **What the worklog can't vouch for** in the range is said at the top. Review waits, the
308
+ sprint and Next aren't on any worklog page, so they are as of the latest sync, and the
309
+ report says which.
310
+ - **Every line links** to its item, pull request or build, and is numbered (F1, F2, ...).
311
+
312
+ It copies as **Markdown** (for Slack, Teams or a wiki) or **plain text**, line for line as
313
+ shown. **Export** writes the Markdown through toil's file service, as a page's export does,
314
+ to `standup-<dossier>-<from>-to-<to>.md`, and publishing it to Confluence or GitHub is a
315
+ proposal for you to run.
316
+
317
+ **Write it up** is optional: it asks the agent for a short narrative of the same report,
318
+ in the theme's voice when that is on. The agent reads the report through its
319
+ `standup_report` tool and ends each sentence with the fact numbers it rests on; the
320
+ write-up is labelled as the agent's, the lines it names are marked in the report, and its
321
+ usage counts like any chat's.
322
+
59
323
  ## Toil's configuration
60
324
 
61
325
  The Settings pages manage what `toil connections` and `toil dossiers` manage, by
@@ -65,20 +329,45 @@ running those commands through `@imagile-dev/toil/api`, never by editing a file:
65
329
  replace a secret (`toil connections login`) and remove. A secret goes from a
66
330
  password field to toil, which keeps it in the OS credential store; the page
67
331
  clears the field, and it is never logged, stored by Toil UI, or sent back.
332
+ A note under the field says how many characters it holds and what trimming
333
+ removes, never the value. The same paste checks as the CLI's run, in the
334
+ CLI's words: a line break (or, for a token, a space) in the middle is
335
+ refused, and quotes or a `Bearer ` / `token ` prefix ask Remove it or Keep
336
+ it before anything is saved.
68
337
  Turning writes on asks you to type the connection's name, as the CLI does. A
69
338
  connection made by `TOIL_*` env vars alone is shown read-only, with where it
70
339
  came from.
71
340
  - **Dossiers:** create one, add a repository, link an area, name a field, and
72
- show and check any of them. A link to a connection with writes on is refused
341
+ show and check any of them. A dossier's name and description are edited in place
342
+ on its card and dashboard, through `toil dossiers describe`. A link to a connection with writes on is refused
73
343
  here, as over MCP: make it on the CLI.
74
344
  - **Bounds and time limit:** toil has no command for these, so they are shown
75
345
  read-only, with the file or env var that sets them.
346
+ - **Usage:** how toil is used on this machine, from `toil audit stats`, which
347
+ reads only toil's local audit log: calls per day, the split between Toil UI, the
348
+ CLI and MCP, the commands used most, the ones that fail most with their top
349
+ error code and its usual fix (and, on request, their recent failures from
350
+ `toil audit list`), and the commands nothing called. It needs a toil with
351
+ `audit stats`, newer than 0.1.0-alpha.3; with an older one the page shows toil's
352
+ error.
76
353
 
77
354
  Every change is an explicit action, runs the command's own checks, and is in
78
355
  toil's audit log as `caller: "toil-ui"`. The page can run no other command on this
79
356
  path, and never a tracker write. Adding or changing connections needs a toil
80
357
  newer than 0.1.0-alpha.2; with that one, use the CLI.
81
358
 
359
+ ## Help and edit links
360
+
361
+ An **(i)** beside a term explains it in a sentence or two when you hover or focus
362
+ it, and pressing it opens the same words with a **Read more** link to the section
363
+ of these docs that says the rest. A **pencil** beside a configurable value (a
364
+ connection, a dossier's sources, people, field names or work-in-progress limit,
365
+ 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.
370
+
82
371
  ## Feedback
83
372
 
84
373
  The **Feedback** button in the header opens a dialog for a bug report or a feature
@@ -108,8 +397,8 @@ dashboards make, for every dossier, and stores the answers. The work items go
108
397
  through toil's Open Work Item mapping, with their status changes and the pull
109
398
  requests, builds and deployments that name them.
110
399
 
111
- - **Incremental.** After the first sync, Jira and Azure DevOps searches ask only for
112
- what changed since the last good sync (`updatedSince`, five minutes early in
400
+ - **Incremental.** After the first sync, Jira and Azure DevOps searches, and a
401
+ GitHub repository's issues, ask only for what changed since the last good sync (`updatedSince`, five minutes early in
113
402
  case the clocks disagree), and the GitHub board marks the issues whose
114
403
  `updatedAt` moved. Only those items and their histories are fetched again.
115
404
  Pull requests, builds, deployments and iterations have no "changed since" in
@@ -125,7 +414,9 @@ requests, builds and deployments that name them.
125
414
  says when each dossier was synced, and shows a running sync's progress
126
415
  (requests, pages and retries, from toil's own progress events).
127
416
  - **Where.** The cache is one SQLite file, `cache/toil-ui.db` in the data folder,
128
- through Node's built-in `node:sqlite`, so there's no native module. It holds
417
+ through Node's built-in `node:sqlite`, so there's no native module. While Toil
418
+ UI runs, its write-ahead log (`toil-ui.db-wal` and `toil-ui.db-shm`) sits beside
419
+ it, and closing folds the log back into the file. It holds
129
420
  ticket content, so it stays on this machine and is readable by your account
130
421
  only.
131
422
  - **For how long.** Anything not synced again within the retention period (30
@@ -141,13 +432,46 @@ requests, builds and deployments that name them.
141
432
  The page can run only the reads the dashboards make: `dossiers list` and `dossiers
142
433
  show`, and each area's search, history, pull request, build and deployment reads.
143
434
  Any other command is refused before it reaches toil, and a change to a tracker is
144
- never made from the page.
435
+ never made from the page. The worklog's own calls are made by the server, never named
436
+ by the page: `toil audit list`, read-only, to see whether a proposal was applied, and
437
+ `toil util encode` for an export you asked for.
145
438
 
146
439
  ## The agent
147
440
 
148
- The docked chat answers with the agent your organization already approved, on the
441
+ Every dossier page has an **Ask bar** under the header: one line, with **Analyze**
442
+ beside it. Pressing into it opens the **focused view**: the conversation takes the
443
+ screen and the page steps back, with a slim strip that keeps the dossier, its sprint
444
+ and the agent answering in sight. **Escape** or **Close** puts it away; the
445
+ conversation stays, for the rest of the dossier's pages, until you reload.
446
+
447
+ - **Starter questions** are a row of chips before the first question, then a
448
+ **Suggestions** menu.
449
+ - **Answers stream in** as the agent writes them, under a **status line** that says
450
+ what it is doing: reading the cache with `owi_query`, reading live through toil with
451
+ `github issue list`, writing, and at the end how long it took. **Stop** cancels the
452
+ question on the server and keeps what had arrived. Claude and Copilot stream as they
453
+ write; Codex's SDK hands over its text a message at a time, so with Codex the status
454
+ line is what moves between messages.
455
+ - **The wording follows the theme**: the bar's placeholder, the welcome and the status
456
+ words are in each game theme's voice, and Plain stays neutral. The starter questions
457
+ read the same in every theme.
458
+ - **Analyze** asks for a pulse check in one press: what changed since the last Analyze
459
+ (from the worklog), who is on what, what is blocked or stuck in review, the sprint's
460
+ health and risks, and anything that looks off, such as a ticket marked done while its
461
+ pull request is open. Every line cites its items, and follow-up questions continue
462
+ from it.
463
+ - **Each question carries the chat so far**: its last 8 questions and answers, each
464
+ answer cut to 1,500 characters. An item an earlier answer named is still checked
465
+ against what the tools return for the new question.
466
+ - **Switch agent from the chat.** The strip's switcher lists Claude, GitHub Copilot and
467
+ Codex, each with its model and whether it can answer. A choice holds for this chat
468
+ from its next question, which carries the conversation so far; the default stays in
469
+ Settings. An adapter that can't answer is listed with the reason and **Install** or
470
+ **Fix**, never left out. Each answer names the adapter and model that wrote it.
471
+
472
+ The chat answers with the agent your organization already approved, on the
149
473
  subscription you already have. Toil UI has three adapters, each an optional peer
150
- dependency that is loaded only when you choose it:
474
+ dependency that is loaded only when it answers:
151
475
 
152
476
  | Adapter | Package | Starts | Signs in with |
153
477
  |---|---|---|---|
@@ -155,16 +479,54 @@ dependency that is loaded only when you choose it:
155
479
  | GitHub Copilot | `@github/copilot-sdk` | `copilot` (the Copilot CLI) | your Copilot seat, through the CLI |
156
480
  | Codex | `@openai/codex-sdk` | `codex` (the Codex CLI) | the CLI's ChatGPT sign-in or its own API key setup |
157
481
 
482
+ Choose the default under **Settings, Agent**: the adapter, each adapter's model
483
+ (empty for its CLI's default), the CLI's path (empty to use the one on `PATH`) and,
484
+ for Claude, the endpoint. The choice is kept in `<data folder>/agent.json`, never in
485
+ toil's config, and has no field for a key: each SDK signs in the way its CLI does.
486
+
487
+ ### Installing an adapter's SDK
488
+
489
+ **Settings, Agent** lists each adapter: whether its SDK is installed and at which
490
+ version against the one Toil UI was tested with, which CLI it would start, and
491
+ anything worth knowing. A missing SDK has an **Install** button, which shows the one
492
+ command it will run, word for word, before anything runs:
493
+
158
494
  ```bash
159
- npm install -g @anthropic-ai/claude-agent-sdk zod # beside a global toil-ui
495
+ npm install --global --prefix <the prefix Toil UI is installed in> --ignore-scripts --before=<14 days ago> --no-audit --no-fund --omit=optional @openai/codex-sdk@0.160.0
160
496
  ```
161
497
 
162
- Then choose it under **Settings, Agent**: the adapter, the model (empty for the CLI's
163
- default), the CLI's path (empty to use the one on `PATH`) and, for Claude, the
164
- endpoint. The choice is kept in `<data folder>/agent.json`, never in toil's config,
165
- and has no field for a key: each SDK signs in the way its CLI does. Install the SDK
166
- with `--omit=optional` if you don't want its bundled copy of the CLI on disk; Toil UI
167
- never starts that copy anyway.
498
+ Pressing **Install** runs it through the npm that came with your Node, with no shell and
499
+ your own npm config, so your organization's registry and proxy apply. npm's output
500
+ streams into the dialog, and Toil UI then loads the SDK to prove it installed; a
501
+ failure shows npm's own message and the fix. **Copy command** is beside it, for a
502
+ machine where you'd rather run it yourself. This is the one thing Toil UI runs npm
503
+ for (docs/decisions/343-ask-up-front.md).
504
+
505
+ - **Only the tested versions**: `@anthropic-ai/claude-agent-sdk@0.3.289` with
506
+ `zod@4.6.5`, `@github/copilot-sdk@1.0.16` and `@openai/codex-sdk@0.160.0`, exactly
507
+ (`ui/server/agents/tested.ts`). Nothing else is ever named, and `--before` holds
508
+ everything npm resolves, the SDK's own dependencies included, to releases at least
509
+ 14 days old.
510
+ - **Where it goes depends on how Toil UI is installed.** Installed globally, the SDK
511
+ is installed globally into the same prefix, read from where Toil UI is rather than
512
+ from npm's config, so a global install under another prefix still lands beside it.
513
+ Its optional dependencies, each SDK's own copy of its CLI, are left out: Toil UI
514
+ never starts them. In a project's `node_modules`, it installs into the project with
515
+ `--save-exact`. In a clone of this repository, it installs at the root with
516
+ `--no-save`, naming the agent SDKs already there again, since an unsaved install
517
+ removes the ones it doesn't name.
518
+ - **Run with `npx`, it can't install**: npx runs Toil UI from its cache, which npm
519
+ clears when it likes, so there is no folder to install beside. The dialog says so;
520
+ install Toil UI with `npm install -g @imagile-dev/toil-ui` and start it as `toil-ui`.
521
+ - **Not into Toil UI's own folder.** Its `package.json` lists the SDKs as optional
522
+ peers, so npm reports them up to date there and installs nothing.
523
+ - **Claude's bundled CLI.** `@anthropic-ai/claude-agent-sdk`'s platform package is an
524
+ optional dependency that npm sometimes skips. Toil UI doesn't need it, since it
525
+ starts the `claude` it finds, and the status says so rather than fail.
526
+ - **Copilot on Windows.** npm installs the Copilot CLI as `copilot.cmd`, a shim no SDK
527
+ can start without a shell. Copilot's SDK starts a `.js` CLI with Node itself, so
528
+ Toil UI starts the script the shim runs (`node_modules\@github\copilot\npm-loader.js`
529
+ beside it) and says so in the status. Claude Code and Codex install as `.exe` files.
168
530
 
169
531
  - **Only the CLI already on this machine.** Toil UI finds it on `PATH` (skipping
170
532
  relative entries and the working directory) or at the path you set, which must
@@ -173,14 +535,25 @@ never starts that copy anyway.
173
535
  and temp folders, proxy and CA settings) and its own sign-in variables. toil's
174
536
  `TOIL_*` variables, `GITHUB_TOKEN` and CI tokens never reach it. Not found is a plain
175
537
  error naming the CLI and the fix. On Windows a `.cmd` shim can't be started by the
176
- SDKs, so point at the `.exe`.
177
- - **Read-only tools, one dossier.** The agent gets `owi_query`, `owi_get` and
178
- `owi_history` over the cache, `proposal_fields` (a write command's input fields,
538
+ SDKs, so point at the `.exe` (Copilot's npm shim is the exception, above).
539
+ - **Read-only tools, one dossier.** The agent gets `owi_query`, `owi_get`,
540
+ `owi_similar` (likely duplicates, scored as `toil util owi similar` scores them)
541
+ and `owi_history` over the cache, `pr_query`, `pr_get` and `pr_metrics` over its
542
+ pull requests (what each waits on, its flags, and flow figures by author kind with
543
+ their sample sizes), `people_list` and `person_get` (each person's plate as the
544
+ People view works it out, with the dossier read live through `dossiers show`, and
545
+ told it describes load, never performance), `readiness_list` and
546
+ `readiness_get` (each item's readiness verdict and its rows, as the Command Center
547
+ works them out), `proposal_fields` (a write command's input fields,
548
+ told it describes load, never performance), `worklog_day` (one day's worklog page,
549
+ with what it can't vouch for), `standup_report` (a range of days as the Stand-up folds
550
+ them, each line numbered), `proposal_fields` (a write command's input fields,
179
551
  from toil's registry), and `toil mcp`'s read tools for live lookups, called through
180
552
  toil's `execute()` with `readOnly: true`. The dossier is fixed to the one on screen.
181
553
  There is no write tool, and each SDK's own tools (shell, files, web, plugins, other
182
554
  MCP servers) are switched off.
183
- - **Citations are checked.** Every answer cites the work items it used as links.
555
+ - **Citations are checked.** Every answer cites the work items and pull requests it
556
+ used as links.
184
557
  The server holds each id it names to what its tools returned, and flags any other
185
558
  as unverified above the answer.
186
559
  - **Writes are proposals.** A change the agent suggests comes back as a card with the
@@ -190,9 +563,233 @@ never starts that copy anyway.
190
563
  Toil UI serves them at `api/agent/mcp` on its own loopback port, behind a token made
191
564
  for that question. The token reaches Codex in its environment, never on its command
192
565
  line, and the endpoint refuses any request carrying a browser's `Origin`.
566
+ - **Codex runs in a Codex home of Toil UI's own**, `<data folder>/cache/codex`, not
567
+ yours. Codex adds whatever its home's config names (MCP servers, profiles, plugins,
568
+ hooks, skills) to what it's given, so with your own home your servers would start
569
+ beside Toil UI's. Toil UI's home holds a `config.toml` it rewrites before every
570
+ question, so `codex mcp list` there shows only `toil_ui`, and `auth.json`, a hard
571
+ link to the one in your Codex home (`$CODEX_HOME`, else `~/.codex`). A hard link is
572
+ the same file under a second name, not a copy: a token Codex refreshes is refreshed
573
+ for both, and once you sign out of Codex the next question removes the link and says
574
+ so. With no `auth.json` (a sign-in kept in the OS keyring, or none), `CODEX_API_KEY`
575
+ in Toil UI's environment signs in instead. Your data folder and your Codex home must
576
+ be on the same drive. `toil-ui wipe` deletes this home with the cache, along with
577
+ Codex's record of Toil UI's questions, and leaves your own `auth.json` alone.
578
+
579
+ - **Your own instructions.** Under **Settings, Agent**, general instructions (for
580
+ example "answer in British English") and a custom voice, each up to 4,000
581
+ characters, kept in `agent.json` beside the adapter. They come after the rules in
582
+ the prompt, and the rules win: they can't change the citations, the figures, the
583
+ proposals or what the tools can do. **Show the full prompt** shows exactly what
584
+ the agent is sent.
585
+
586
+ With no adapter chosen, the chat says so and names the three; its switcher can still
587
+ choose an installed one for that chat. `toil-ui --sample` keeps the scripted agent,
588
+ which answers its starter questions and Analyze from the sample data.
589
+
590
+ ### Not ticketed yet
591
+
592
+ When you ask the chat for work that names no ticket (not a question, which ends in `?` or
593
+ opens with what, why, how and the like, and no key such as `PAY-12` or `#42`), a **Not ticketed yet** banner lists up to three of the
594
+ dossier's open items likeliest to cover it, scored as `toil util owi similar` scores
595
+ them, each with why. Attach the work to one by naming its key in your branch and
596
+ commits, which writes nothing, or press **Ticket this** for proposals: a sub-task
597
+ under each match, and a new ticket on the dossier's tracker. They are proposal cards
598
+ like the chat's others, with the command line to run through toil's write gate, and
599
+ nothing is created until you run one. With no match, it says there is no likely
600
+ ticket and offers only a new one. It asks once per chat, and **Not now** hides it.
601
+
602
+ ### What the agent's models used
603
+
604
+ Each SDK reports what a question used, and Toil UI keeps that report, one record per
605
+ model call or running total, read only from the SDK's own events (no billing API is
606
+ called):
193
607
 
194
- With no adapter chosen, the chat says so and names the three. `toil-ui --sample`
195
- keeps the scripted agent, which answers its starter questions from the sample data.
608
+ | Adapter | What the SDK reports | What Toil UI shows |
609
+ |---|---|---|
610
+ | Claude | each step's `usage` by message id, then the result's `modelUsage` per model and its `costUSD` | tokens (in, out, cache read, cache write) per model, and the dollar figure as the SDK's estimate; on a Claude plan (no API key, Anthropic's own API) it says "API-equivalent", since the plan isn't billed per token |
611
+ | Codex | `turn.completed`'s `usage`: input (which holds the cached input), cached input, cache writes, output | tokens; a dollar figure only from rates you enter, labelled "computed from your rates". The SDK names no model, so a Codex record names the model you chose, or says it wasn't named |
612
+ | GitHub Copilot | one `assistant.usage` event per model call, with `cost` as the premium-request multiplier, and `session.usage_info` for the context. Copilot bills the multiplier once per prompt: only the call the prompt started (`initiator` `user`) counts it, and the agent's follow-up calls in the tool loop count 0 | tokens and premium requests, never dollars; premium requests left from the SDK's experimental `account.getQuota`, marked experimental |
613
+
614
+ - **Under each answer**, one line per model: `2.1k in · 380 out · 14k cached · cache
615
+ write not reported · ~$0.012 (SDK estimate)`. A figure the SDK didn't report reads
616
+ "not reported", never 0.
617
+ - **In the chat's heading**, the chat's running total, split by model, and how full
618
+ the last answer's context got, where the SDK says (Claude and Copilot; Codex's SDK
619
+ doesn't).
620
+ - **Settings, Agent usage** (beside Usage, which counts toil's own commands): the last
621
+ 30 days by day, adapter, model and dossier, the chats that used the most, and an
622
+ **Export as CSV** download made in the page.
623
+ - **One adding-up rule**, `addUp` in `src/model-usage.ts`, read by the server's caps,
624
+ the footer, the heading and Settings: reports with one id are one report, merged to
625
+ the highest of each figure (a running total), and different ids are summed.
626
+ - **The ledger** is the cache's `usage` table, apart from everything a sync writes: a
627
+ sync's cleanup or a dossier leaving never lowers a total. It follows the cache's
628
+ retention, `toil-ui wipe` clears it, and it is never sent anywhere.
629
+
630
+ **Caps** are optional and off until you turn one on, under Settings, Agent usage: a
631
+ per-chat and a per-day (UTC) cap for each adapter, in tokens, dollars (Claude's SDK
632
+ estimate, or Codex from your rates) or Copilot premium requests. At 80% the answer
633
+ says so; at 100% the question stops, naming the cap and how to raise it. Claude and
634
+ Copilot report each call as it happens, so their caps stop a run partway; Codex
635
+ reports when an answer ends, so its cap refuses the next question. They live in
636
+ `<data folder>/usage.json`, with the Codex rates. A value that doesn't parse is
637
+ refused, naming the setting, and while the file can't be read the agent answers
638
+ nothing, so a typo can never turn a cap off. A cap counts only what the SDK reports:
639
+ the vendor's own bill is the authority.
640
+
641
+ ## Assigning work to an agent
642
+
643
+ From an item's page, or **Assign to an agent…** in its card's menu on the board
644
+ (right-click the card, long-press it, or press M while it has focus), a work item can be
645
+ assigned to Claude, GitHub Copilot or Codex in one of three modes. The agent works on
646
+ the subscription you already have, and nothing it proposes leaves this machine until
647
+ you apply it.
648
+
649
+ | Mode | What the agent does | What it can change |
650
+ |---|---|---|
651
+ | **Refine** | Checks for duplicates, drafts acceptance criteria, suggests an estimate, splits the item into children where it is too big, and asks its open questions | Nothing: every change is a proposal |
652
+ | **Investigate** | Reads the item, its parent, children, links, likely duplicates, pull requests and toil's live reads, and writes a report that cites each source | Nothing: the report is kept with the assignment, and posting it as a comment is a proposal |
653
+ | **Implement** | Works in a copy of the dossier repository's git folder that Toil UI makes in a folder of its own, fills it from the last commit, makes the branch `agent/<key>`, changes and tests the code, and stages the change | Only that clone, with no network. Committing, pushing and opening a pull request are proposals |
654
+
655
+ - **Refine and investigate** get the same read-only tools as the chat (`owi_*`, `pr_*`,
656
+ `proposal_fields` and toil's live reads), with no shell and no file writes.
657
+ - **Implement runs on Codex only, for now.** Codex's own sandbox, `workspace-write`,
658
+ holds the agent's commands and writes to the clone, with no network and none of the
659
+ temp folders Codex adds by default, on Windows (its `unelevated` restricted-token sandbox), macOS and Linux. The clone is
660
+ `<data folder>/cache/work/<assignment>/repo`, so `toil-ui wipe` deletes it; before any git runs there outside the sandbox, Toil UI rewrites its git config and removes its hooks. The dossier's
661
+ repository needs a local path (`toil dossiers add-repo <dossier> <folder>`). The agent stages its change and never commits, pushes or fetches; the
662
+ staged diff is shown through toil's own `git status` and `git diff`, and the commit
663
+ and push are a proposal of the exact git lines to run, since toil has no command
664
+ that pushes.
665
+ - **States**: `queued` (waiting for a free slot, or for a person to press Start),
666
+ `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.
670
+ - **From the Command Center**, "Start every ready item" assigns each slated item in
671
+ implement mode, in order, on Codex (or the adapter chosen in Settings, when it can
672
+ implement), in the dossier's one repository with a local path, and says what it
673
+ queued or why it started nothing.
674
+ - **The tracker only queues.** An item labelled `agent:refine`, `agent:investigate` or
675
+ `agent:implement`, or assigned to one of the dossier's agents (its `people` with
676
+ `kind: agent`, which queues a refine), appears in the **Agent inbox** on the next
677
+ read. It runs only when a person presses Start.
678
+ - **Applying a proposal** runs its toil command, the one the server stored when the
679
+ run ended, through toil's write gate: the connection needs `writes: true`, and your
680
+ press of Apply is the call's `--allow-write`. Each call toil makes for an assignment
681
+ is in toil's audit log with `caller: "toil-ui"` and `actor: "assignment-<id>"`.
682
+ - **Tracker text is untrusted.** The item is fenced off in the prompt as data, and an
683
+ item that tells the agent to do anything else stops the run, marked `needs you`.
684
+ - **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
686
+ `<data folder>/assignments.json`. An assignment is one chat to the usage caps under
687
+ **Settings, Agent usage**, so a per-chat cap is a per-assignment cap. Either limit
688
+ stops a run cleanly, saying which.
689
+ - **The transcript** keeps the prompts, every tool call, the agent's text, the
690
+ commands and file changes Codex reports, and each proposal and what came of it.
691
+ Each assignment also records what it started on: the toil and Toil UI versions, the
692
+ adapter and model, the tools, and SHA-256 fingerprints of the dossier, the item and
693
+ the prompt, and the install fingerprint a later look holds it to (Stale sessions, below). Assignments are kept under the cache, in
694
+ `<data folder>/cache/assignments/`, so a wipe deletes them.
695
+ - **For programs on the same server**, `api/assignments` lists, assigns, starts,
696
+ stops, applies, dismisses and renews, and `api/assignments/events?since=<n>` streams every
697
+ change of state as NDJSON.
698
+
699
+ ## Stale sessions
700
+
701
+ An agent works from the instructions it got when it started. Upgrade toil, edit the
702
+ dossier or change your instructions under **Settings, Agent**, and the chats and
703
+ assignments already going are still on the old ones. Toil UI records what each one
704
+ started on, says which have gone stale and why, and renews them on request.
705
+
706
+ - **What it records.** Each chat at its first question, and each assignment when its
707
+ run starts, keeps an install fingerprint: toil's and Toil UI's version and commit,
708
+ one SHA-256 per toil area of the tools the agent was handed (Toil UI loads no skill
709
+ page, so those tools are the toil instructions its agent reads), SHA-256 of the
710
+ dossier as `toil dossiers show` reads it, and SHA-256 of the prompts (the system
711
+ prompt, the starters or the mode's task, and your own instructions and voice). The
712
+ theme on screen isn't part of it. An assignment recorded before this has none, and
713
+ is never called stale.
714
+ - **When it's stale.** Every answer, every read of the Agents lane and every
715
+ assignment page compares what the session started on with the current fingerprint,
716
+ whose builds are the ones on disk, read again only when their files change. The
717
+ reason names what moved: "started on toil 0.1.0-alpha.3 · now alpha.4 · skills
718
+ changed: github · dossier changed". A session's earlier turns aren't marked; only
719
+ the instructions it started on are.
720
+ - **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
722
+ agent's card in the People view. A done assignment is closed and isn't marked.
723
+ - **Renew.** On the chat, **Renew** in the focused view records what it starts on now;
724
+ the conversation stays, and the next question carries it as every question does. The
725
+ chat's usage total carries on, so renewing never resets a cap. On a stale assignment
726
+ that has failed, **Renew** queues a fresh one on the same item, mode, adapter and
727
+ repository, whose prompt carries what the old run left, fenced as data; the old one
728
+ stays readable, marked as renewed. Renew never interrupts a turn: a chat that is
729
+ answering and a working assignment wait, and an assignment that needs you is
730
+ skipped until you've reviewed it.
731
+ - **Renew all stale**, in the Agents lane, lists every stale session of the dossier
732
+ first, the chat included, each saying whether it renews or why it's skipped, and
733
+ renews the rest with one press.
734
+ - **The server itself.** When toil or Toil UI on disk is newer than the running
735
+ server, the header says so, with the command that starts it again. A session renewed
736
+ then would start on the old build and be stale at once, so until it restarts, Renew
737
+ is refused (and Renew all stale skips every session), saying so with that command.
738
+
739
+ ## Notifications
740
+
741
+ Toil UI tells you when an agent's state changes, and stays quiet otherwise. A tool
742
+ call, its progress, or a state that didn't change never notifies.
743
+
744
+ - **What notifies:** an assignment reaching **needs you** (with why: "asked a
745
+ question", "3 proposals to review"), **done** or **failed**, one stopped at its
746
+ **usage cap**, and a chat or assignment gone **stale** (Stale sessions, above). A
747
+ run going from queued to working says nothing, and neither does your own Stop.
748
+ - **Once, together.** Changes within four seconds become one notice: "2 agents need
749
+ you", each line linking to its assignment. A change undone inside those seconds,
750
+ such as a question answered elsewhere, sends nothing.
751
+ - **Where.** A notice under the header, with Dismiss. While the tab is hidden its
752
+ title counts them, `(2) Toil UI`, until you come back. With **Browser
753
+ notifications** on, the browser's own notification shows them too, drawn on this
754
+ computer: nothing leaves the machine. The browser is asked for permission only when
755
+ you turn that on, never before.
756
+ - **Settings**, under **Settings, General**, kept in this browser: a switch for each
757
+ kind (**needs you**, **failed** and the usage cap on, **done** off, **stale** on, by
758
+ default), **only for agents I started** (the chats in this browser and the
759
+ assignments assigned, started or renewed here), and quiet hours, which hold every
760
+ notice while the title still counts.
761
+ - **Plain words.** Notices read the same in every theme: the theme's wording stays in
762
+ the views.
763
+ - **Where it listens.** The server's `api/assignments/events?since=latest` stream,
764
+ which carries what a notice says with each event, and a minute's read of the
765
+ dossier on screen for sessions gone stale.
766
+
767
+ ## Themes
768
+
769
+ Five built-in themes: Plain, Crate (the default), Harvest, Starship and Realm. Pick
770
+ one from the header, or under **Settings, General**, where two checkboxes say how far
771
+ it goes, both on by default:
772
+
773
+ - **Themed wording:** the theme's own lede, eyebrows, dashboard notes, empty
774
+ states and loading lines, and its names for a sprint, a board or an epic beside
775
+ the real ones ("Campaign (Epic)"). Buttons, links, figures, ids, commands and errors
776
+ read the same in every theme.
777
+ - **Themed agent voice:** the agent answers in the theme's register, a terse
778
+ 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.
780
+
781
+ A theme with particles also gets **Particles and ambient effects**, kept for each
782
+ theme on its own: off, that theme's particles are gone entirely, while its other
783
+ motion keeps following **Reduce motion and effects** (and the operating system's
784
+ reduced-motion setting, which stops everything).
785
+
786
+ 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
789
+ feature request from **Feedback** or with `toil feedback feature`. A `themes/` folder
790
+ left in the data folder by an earlier alpha is not read, and Toil UI says so when it
791
+ starts. [Themes](https://imagile-dev.github.io/toil/docs/themes/) has the whole
792
+ story, the composed prompt included.
196
793
 
197
794
  ## The lock on the door
198
795
 
@@ -209,6 +806,200 @@ port, so the server lets in only the browser holding this launch's token:
209
806
  - **No network but toil's.** It talks to the hosts in your toil connections, and
210
807
  nothing else, apart from a feedback report you send, which toil sends to Imagile. The agent CLI you choose talks to its own model endpoint.
211
808
 
809
+ ## Run against a real repository
810
+
811
+ From a clone, one command starts Toil UI on a real GitHub repository, in a home
812
+ folder of its own (`.scratch/home` in the clone, ignored by git), so your own
813
+ `~/.toil` and `~/.toil-ui` are never read or written:
814
+
815
+ ```bash
816
+ npm ci --ignore-scripts
817
+ npm run build -w ui
818
+ node ui/scripts/dev-real.mjs
819
+ ```
820
+
821
+ It works the same in PowerShell, Git Bash and a macOS or Linux shell. It needs the
822
+ GitHub CLI signed in (`gh auth login`), or `TOIL_GITHUB_TOKEN` set in the shell.
823
+
824
+ - **toil's config**, written once: one connection, `github`, to
825
+ `https://api.github.com`, with writes off and no token in the file.
826
+ - **The token** comes from `gh auth token` each time it starts and goes only into
827
+ Toil UI's environment, as `TOIL_GITHUB_TOKEN`. It's never written to a file or
828
+ printed. `GITHUB_TOKEN` and other `TOIL_*` variables in your shell are left out.
829
+ - **The dossiers**, made with `toil dossiers init` and `link` and checked with
830
+ `toil dossiers check`: one for `--repo`, and `toil-self` for the public
831
+ `imagile-dev/toil` unless `--no-self`. `--repo` defaults to
832
+ `imagile-dev/toil-sandbox` (as `sandbox`), which is private to Imagile's
833
+ maintainers; anyone else passes their own repository, or seeds a sandbox of their
834
+ own (below).
835
+ - **toil from this checkout.** Each start builds toil from the clone into
836
+ `.scratch/toil` (`npm run build` with `TOIL_BUILD_DIR`, a few seconds), and both the
837
+ dossier setup and Toil UI run on that build, not on the published toil
838
+ `ui/package.json` pins. Toil UI is started with `node --import
839
+ ui/scripts/local-toil-hook.mjs`, which resolves `@imagile-dev/toil/api` to
840
+ `.scratch/toil/api.js` and says so on stderr. So a command `ui/` calls before its
841
+ release works here. The committed `dist/` and `node_modules` are left alone, and a
842
+ plain `node ui/dist/server/toil-ui.js` still runs on the pinned toil.
843
+ - **Then** it starts `ui/dist/server/toil-ui.js` on loopback and prints its URL.
844
+ Press **Sync now**, then open a dossier. `--port <n>` fixes the port, and
845
+ `--home <dir>` uses another folder.
846
+ - **Ask with Codex.** Install the SDK in the clone without saving it
847
+ (`npm install --no-save --ignore-scripts @openai/codex-sdk@0.160.0`), then choose
848
+ Codex under **Settings, Agent**. The script points `CODEX_HOME` at your real
849
+ `~/.codex`, which is where Toil UI finds the `auth.json` it links into its own
850
+ Codex home.
851
+ - **Ask with GitHub Copilot, on a cheap model.** Install `@github/copilot-sdk@1.0.16`
852
+ the same way (or press **Install** under **Settings, Agent**). The Copilot CLI found
853
+ its own sign-in from the scratch home in our runs; if it says it isn't signed in, run
854
+ `copilot` once on its own. Then pick the model: Copilot lists the models your
855
+ account can use, each with its premium-request multiplier (`/model` in the CLI, or
856
+ the SDK's `listModels()`). Choose the lowest, ideally one at 0×; otherwise the
857
+ cheapest multiplier, such as `mai-code-1.1-flash` at 0.25×, never a premium model.
858
+ Type its id as Copilot's model under **Settings, Agent**, and check the model each
859
+ answer names and the premium requests under it.
860
+ - **Ask with Claude, on Haiku.** Install `@anthropic-ai/claude-agent-sdk@0.3.289` and
861
+ `zod@4.6.5` the same way, and type `haiku` (or `claude-haiku-5-5`) as Claude's
862
+ model under **Settings, Agent**; empty would be Claude Code's own default, which
863
+ may be Opus. Claude Code keeps its sign-in in `~/.claude`, which the scratch home
864
+ hides, and refreshing it from there would rewrite your credentials file, so the
865
+ script only reads it: a `CLAUDE_CODE_OAUTH_TOKEN` or `ANTHROPIC_API_KEY` in the
866
+ shell goes through as it is, and otherwise the access token in
867
+ `~/.claude/.credentials.json` goes into Toil UI's environment as
868
+ `CLAUDE_CODE_OAUTH_TOKEN` while it has ten minutes left. When it has expired the
869
+ script says so: run `claude` once in a terminal, which refreshes its own sign-in,
870
+ or set a token from `claude setup-token`, and start the script again.
871
+
872
+ ## Verify before you open a PR: `npm run verify:ui`
873
+
874
+ One command checks Toil UI the way a reviewer would, and writes what it found to
875
+ `ui/.verify/report.md` with screenshots beside it (git ignores the folder). Run it
876
+ from the root or from `ui/`, and paste the report's table into the PR.
877
+
878
+ ```bash
879
+ npm run verify:ui # build, sample data, real data
880
+ npm run verify:ui -- --ask # and one Codex question
881
+ npm run verify:ui -- --ask --adapter copilot --model mai-code-1.1-flash # or --adapter claude --model haiku
882
+ npm run verify:ui -- --no-build --starter standup
883
+ ```
884
+
885
+ - **It builds Toil UI and toil**, unless `--no-build`: toil from this checkout into
886
+ `.scratch/toil`, which Toil UI runs on, as `dev-real.mjs` does (above). The report's
887
+ header and its **Toil** row name that toil: its version, the commit it was built
888
+ at, and whether `src/` had uncommitted changes. The run fails if Toil UI didn't
889
+ resolve `@imagile-dev/toil/api` to it. It also confirms that the toil `npm ci`
890
+ installs is the one `ui/package.json` pins (`npm run check:lockfile -w ui`), which
891
+ is what the published package runs on.
892
+ - **Sample data:** `toil-ui --sample` in a throwaway home, every view through the
893
+ 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.
895
+ - **Real data:** the home `dev-real.mjs` sets up, made fresh at
896
+ `.scratch/verify/home`, on `imagile-dev/toil-sandbox` with the token from `gh auth
897
+ 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,
899
+ except that its header may fold into the Menu at 1440px, since a real dossier's name
900
+ and links can genuinely fill the row.
901
+ Without a GitHub sign-in it skips this part and says so; nothing else depends on it.
902
+ - **`--ask`** asks Codex one starter question (`hygiene` unless `--starter <id>`) and
903
+ checks that an answer arrived, that the server verified every `[[id]]` it cites,
904
+ that its proposals parsed, that nothing ran (no write in toil's audit log for the
905
+ 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
907
+ SDK installed in the clone (above). `--adapter copilot` or `--adapter claude` asks that
908
+ adapter instead, held to the same checks (Codex is the reference; its MCP check is
909
+ skipped), and `--model <id>` sets its model and fails the run when an answer or a
910
+ usage record names another one, so a cheap-model run can't quietly use a dear one. Each adapter's full live run, every agent feature on the sandbox, is
911
+ recorded in `ui/docs/live-runs/`.
912
+ - **What fails it:** any layout problem in any theme, and any axe violation at WCAG
913
+ 2.2 AA in Plain and Crate. Axe findings in the other themes are listed in the report
914
+ and never fail it. Screenshots are of Plain and Crate.
915
+ - **It stops** every server and browser it started, and exits 1 on any problem.
916
+
917
+ `--source ado` runs the real-data part against an Azure DevOps Services board
918
+ instead (the `ado-board` dossier, as `dev-real.mjs --source ado` makes it below),
919
+ with `TOIL_ADO_CLOUD_BASE_URL`, `TOIL_ADO_CLOUD_PAT` and `--project <name>` (else
920
+ `TOIL_ADO_CLOUD_PROJECT`); without them it skips that part and says why. Each source is
921
+ one entry in `SOURCES` in `scripts/verify.mjs`. Set `CHROME_PATH` if the browser it finds doesn't draw headless; Playwright's
922
+ Chromium works where an installed Chrome doesn't.
923
+
924
+ ### The sandbox repository
925
+
926
+ `imagile-dev/toil-sandbox` is a private repository of made-up work for trying
927
+ this, and the seed below makes the same in a repository of yours: labels for type, priority, points and blocked; three milestones as sprints
928
+ (41 closed, 42 current, 43 next); 25 issues, open and closed, some assigned, some
929
+ blocked by others, a few unestimated, one with a very long title; a workflow that
930
+ only echoes, with one branch that fails on purpose; four pull requests that
931
+ close issues (merged, open, draft, and one with a failing build); and comment
932
+ reviews on two of them. GitHub won't let a pull request's author approve it or be
933
+ asked to review it, so review requests are seeded only when the repository has a
934
+ second collaborator to ask; with one, the seed says it skipped them.
935
+
936
+ ```bash
937
+ gh repo create <owner>/toil-sandbox --private --add-readme
938
+ node ui/scripts/seed-sandbox.mjs --owner <owner> --repo toil-sandbox
939
+ ```
940
+
941
+ The seed writes through the GitHub CLI's own login, never through toil, and is
942
+ safe to run again: what exists is found by name or title and left alone. To start
943
+ over, delete the repository (`gh repo delete <owner>/toil-sandbox`, which needs the
944
+ `delete_repo` scope), create it again and re-run the seed. It adds no Projects
945
+ board, which needs the `project` scope on the token, and no deployments, which
946
+ toil's `github` area doesn't read.
947
+
948
+ ### An Azure DevOps Services board
949
+
950
+ `--source ado` runs the same way against an Azure DevOps Services project, through
951
+ toil's `ado-cloud` area, with a dossier named `ado-board`:
952
+
953
+ ```bash
954
+ node ui/scripts/dev-real.mjs --source ado --project "<project>"
955
+ ```
956
+
957
+ It needs `TOIL_ADO_CLOUD_BASE_URL` (`https://dev.azure.com/<organization>`) and
958
+ `TOIL_ADO_CLOUD_PAT` (an organization-scoped token with Work Items, Read) in the
959
+ shell. They go into Toil UI's environment only: toil makes its `ado-cloud`
960
+ connection from them, with writes off, and nothing about the organization is
961
+ written to the config file. `--project`, or `TOIL_ADO_CLOUD_PROJECT`, names the
962
+ project; the dossier in the scratch home holds it. The dossier names no repository,
963
+ so no pull requests are read; add `repo` to its `ado-cloud` section for them.
964
+
965
+ To fill a board with made-up work, `ui/scripts/ado-seed/` seeds one from Open Work
966
+ Items. `items.owi.json` holds 45 of them across the three sample products
967
+ (`card-payments`, `settlement`, `checkout-web`): Scrum epics, features, backlog
968
+ items, tasks and bugs, in a mix of states, in Sprints 1 to 3 and the backlog, with
969
+ efforts (some missing), acceptance criteria (some missing), parents, dependencies,
970
+ related pairs, long titles and two stale items. It's written by a seeded generator,
971
+ so the same seed always gives the same file:
972
+
973
+ ```bash
974
+ node ui/scripts/ado-seed/generate.mjs # writes items.owi.json, checked against docs/owi/schema.json
975
+ node ui/scripts/ado-seed/apply.mjs --project "<project>" --dry-run # what it would create; sends no write
976
+ node ui/scripts/ado-seed/apply.mjs --project "<project>" # creates what's missing
977
+ node ui/scripts/ado-seed/cleanup.mjs --project "<project>" # lists the seeded items, deletes nothing
978
+ node ui/scripts/ado-seed/cleanup.mjs --project "<project>" --confirm <code> # sends exactly that list to the recycle bin
979
+ ```
980
+
981
+ The scripts read the same two variables, create and change work items only, in
982
+ sprints that already exist (a missing sprint stops the run; none is ever created),
983
+ and touch only items tagged `toil-seed` with one `seed:<key>` tag. Every item gets
984
+ both. Running `apply.mjs` again creates only what's missing. Each item's history is
985
+ backdated to its timeline when the token's identity may bypass rules, and seeded with
986
+ ordinary transitions dated today when not, which the run says. `cleanup.mjs` deletes
987
+ only after a dry run has listed the items: the code it prints is made from their ids,
988
+ and `--confirm` refuses a code for any other list. Deleted items can be restored from
989
+ the project's recycle bin. To start over, clean up and apply again.
990
+
991
+ To check what toil reads back, map the board's output and compare it with the file:
992
+ `compare.mjs` matches each item to its record by its `seed:` tag and prints every
993
+ difference, leaving out what the server assigns.
994
+
995
+ ```bash
996
+ toil ado-cloud work-item iterations --project "<project>" > board.jsonl
997
+ toil ado-cloud work-item get-many <ids…> >> board.jsonl
998
+ toil ado-cloud work-item history <id> >> board.jsonl # once for each id
999
+ toil util owi map board.jsonl > mapped.json
1000
+ node ui/scripts/ado-seed/compare.mjs mapped.json --project "<project>" --backdated
1001
+ ```
1002
+
212
1003
  ## Settings
213
1004
 
214
1005
  | Setting | Flag | Env var | Default |
@@ -221,18 +1012,19 @@ port, so the server lets in only the browser holding this launch's token:
221
1012
 
222
1013
  A flag beats its env var. Any bind address other than loopback is refused in this
223
1014
  release. The data folder is Toil UI's own, apart from toil's `~/.toil/`, and holds
224
- the cache. A `~` at the start of `TOIL_UI_DATA_DIR` means your home folder, on
1015
+ the cache, `agent.json` and `usage.json`. A `~` at the start of `TOIL_UI_DATA_DIR` means your home folder, on
225
1016
  Windows too.
226
1017
 
227
1018
  ## Not in this alpha
228
1019
 
229
1020
  - **Serving other machines.** It is local only.
1021
+ - **Implement mode on Claude or Copilot**, and **answering an agent's questions in the assignment** itself: answer on the item and assign it again.
230
1022
 
231
1023
  ## The package
232
1024
 
233
1025
  `@imagile-dev/toil-ui` ships the server (`dist/server/toil-ui.js`) and the built app
234
1026
  (`dist/app/`), and nothing else. It has no install scripts and no native addons,
235
- spawns no program of its own (an agent SDK you install starts its CLI), and its
1027
+ spawns no program of its own but npm, for Install alone (an agent SDK you install starts its CLI), and its
236
1028
  front end's framework is built in rather than installed. The agent SDKs are
237
1029
  optional peer dependencies: none is installed with it.
238
1030