@imagile-dev/toil-ui 0.1.0-beta.2 → 0.1.0-beta.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.
package/README.md CHANGED
@@ -22,9 +22,9 @@ npx @imagile-dev/toil-ui
22
22
  ```
23
23
 
24
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
25
- the exact version it was built with. Until a version shows on
26
- [npm](https://www.npmjs.com/package/@imagile-dev/toil-ui), run it from a clone of
27
- the repository:
25
+ the exact version it was built with. It is published on
26
+ [npm](https://www.npmjs.com/package/@imagile-dev/toil-ui). To run the checkout you
27
+ are reading instead, build it from a clone of the repository:
28
28
 
29
29
  ```bash
30
30
  npm ci --ignore-scripts
@@ -35,7 +35,7 @@ node ui/dist/server/toil-ui.js
35
35
  It prints one URL and keeps running until you press Ctrl+C:
36
36
 
37
37
  ```text
38
- Toil UI 0.1.0-beta.1 (beta, local only), on toil 0.1.0-beta.1
38
+ Toil UI <version> (beta, local only), on toil <version>
39
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.
40
40
  The cache is /home/you/.toil-ui/cache/toil-ui.db, kept 30 days after each sync; toil-ui wipe deletes it.
41
41
 
@@ -43,10 +43,18 @@ Open this URL in your browser. It carries this launch's token, so keep it to you
43
43
  http://127.0.0.1:53117/?token=<token>
44
44
  ```
45
45
 
46
- Open that URL. The page trades the token for a session it keeps in memory, and the
47
- token leaves the address bar. A reloaded page forgets its session, so open the URL
48
- again to get back in. Each start prints a new token. Toil UI opens no browser
49
- itself.
46
+ Open that URL. The page trades the token for a session, and the token leaves the
47
+ address bar. The tab keeps the session in `sessionStorage`, so reloading the page
48
+ works. A new tab needs the URL again, and so does a restart of `toil-ui`, which always
49
+ ends the session; each start prints a new token. A duplicated tab, or one the browser
50
+ restores, can carry the session while the same `toil-ui` is still running. Toil UI opens no browser itself.
51
+
52
+ Why the token, and why `sessionStorage`: the server can run toil with your own
53
+ connections, so something has to keep other local processes and users out of it, and
54
+ the token is that lock. A cookie would have made reloads easy, but a browser sends a
55
+ cookie to every port on `127.0.0.1`, so any other local server would receive the
56
+ session. `sessionStorage` belongs to this exact origin (port included) and is never
57
+ sent anywhere. `localStorage` would outlive the tab, so it isn't used.
50
58
 
51
59
  `toil-ui --sample` serves the sample dossiers and the scripted agent that
52
60
  [the site's Toil UI page](https://imagile-dev.github.io/toil/ui/) runs on, with
@@ -57,7 +65,7 @@ nothing connected to a tracker.
57
65
  Until you have a dossier and it has synced once, the Dossiers view shows a short
58
66
  checklist in place of the empty page:
59
67
 
60
- 1. **Connect a tracker** opens Settings, Connections at the add form.
68
+ 1. **Connect a tracker** opens Settings, Connections at the add form. If an agent following the toil skill's `setup.md` already created the connection, you only enter its secret here, on its row.
61
69
  2. **Create a dossier** opens Settings, Dossiers at Create a dossier.
62
70
  3. **Sync** starts the first sync, as the Sync panel's Sync now does.
63
71
 
@@ -84,6 +92,11 @@ in-process through `@imagile-dev/toil/api`, read-only, and toil's audit log
84
92
  records it with `via: "api"` and `caller: "toil-ui"`. A call that fails shows on
85
93
  its own panel with toil's message and fix.
86
94
 
95
+ Jira and Azure DevOps are read for their open items plus anything changed within
96
+ the read window: the retention period, but at least 6 weeks (42 days), so the
97
+ longest view stays whole. A closed item older than that isn't read, and so isn't
98
+ in any view.
99
+
87
100
  ## The Dossiers view
88
101
 
89
102
  Toil UI opens on its dossiers, one card each, read from the same data the dashboards
@@ -125,7 +138,7 @@ sync reads the dossier afresh under its new name.
125
138
 
126
139
  ## The dossier page
127
140
 
128
- A dossier opens on its **Overview**, in a frame all of its pages share:
141
+ A dossier opens on its **Overview**, the briefing, in a frame all of its pages share:
129
142
 
130
143
  - **The top row:** its name, with the pencil that renames it; **Switch**, for another
131
144
  dossier or the Dossiers view; the sprint and its day; its description, cut to one
@@ -143,6 +156,8 @@ A dossier opens on its **Overview**, in a frame all of its pages share:
143
156
  in three groups (those that need you, those working, and those gone stale), with the
144
157
  finished ones under **Earlier**; then **Renew all stale**, the **Limits**, and this
145
158
  dossier's three newest analyses, each linking to it (Assigning work to an agent, below).
159
+ While an item's drawer is open (`?item=<id>`, The briefing, below), it takes the
160
+ sidebar's column from 1200px wide, and covers the view from the right below that.
146
161
  - **Analyses** lists every Analyze kept for the dossier, newest first: when it was made,
147
162
  the adapter and model that wrote it, its one-line recommendation, and what changed
148
163
  since the one before (items newly blocked or blocked by something new, blockers
@@ -154,41 +169,61 @@ A dossier opens on its **Overview**, in a frame all of its pages share:
154
169
  cache, below), so they outlast a reload and a restart; with `--sample`,
155
170
  card-payments starts with two, kept in memory for the run.
156
171
 
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.
172
+ ### The briefing
173
+
174
+ A dossier opens on its briefing: one column to read top to bottom, each part a step
175
+ further in, and each step one you choose (#494).
176
+
177
+ 1. **The recommendation:** the one thing to do first, as a sentence. Over it, the
178
+ sprint and its day, and who wrote the briefing: the latest Analyze, when it is
179
+ current (made since the data was read, or the same UTC day) and answered with a
180
+ briefing, with who wrote it, when, and a link to it; otherwise toil's briefing by
181
+ code (`toil dossiers brief`, `src/core/brief/`), with no agent call, which says so,
182
+ and why when an older Analyze exists.
183
+ 2. **Why:** the reasons, one line each, the first open and the rest folded: Failing
184
+ checks, Blocked, Waiting on review, Sprint at risk, Stale, Over the WIP limit, and
185
+ Ticket and pull request disagree, in the dossier's order. Each item is under one
186
+ reason only, as a row with its key, title and assignee. Then **On track**, counted
187
+ rather than listed.
188
+ 3. **One step in:** anything the dossier's focus left out, with why, and anything the
189
+ code flagged that Analyze didn't mention, so nothing drops off the page unsaid. An
190
+ id Analyze named that isn't the dossier's is shown in red.
191
+ 4. **The numbers**, folded: burn-up, throughput, cycle time, aging work in progress
192
+ and pull request wait, each opening its full chart.
193
+ 5. **Go to:** every other view, as well as its tab.
194
+
195
+ A row, or any item link on the briefing, opens the item's **drawer** at the page's
196
+ own address plus `?item=<id>`: beside the view at 1200px and wider, over it below
197
+ that. It says why the item is there and who said so, the next step when Analyze
198
+ wrote one, any change Analyze proposed for it, its pull requests and the chain it's
199
+ in, with **Open** for its page and a link to it in its tracker. A Board card's key
200
+ and the items on Pull requests open the same drawer. Escape or **Close** goes back
201
+ to the view behind it.
202
+
203
+ #### Tuning Analyze
204
+
205
+ Each dossier tunes how Analyze briefs it, under **Settings → Dossiers**, **How
206
+ Analyze briefs** (`#/settings/dossiers/<name>/analyze`): its goal, who it's written
207
+ for, its lenses in order with their thresholds, and what else to watch for or leave
208
+ out, the lenses folded until you open them. **The prompt Analyze will send**, under
209
+ the form, shows it as you type, composed by toil's own code, and **Save** runs
210
+ `toil dossiers analyze set` with only what you changed, the line it runs shown under
211
+ the form. The settings live in the dossier file, so a team that shares the dossier
212
+ shares them; whenever a dossier tunes Analyze, the briefing names the file and
213
+ whether it's your own, and a focus from a dossier you haven't adopted still applies.
214
+ Clearing a setting is a delete, made in a terminal. Toil UI composes the preview with
215
+ the toil code it's built with, and Analyze asks the toil it runs on, so the two match
216
+ when Toil UI and toil are released together.
217
+
218
+ #### Customize
219
+
220
+ **Customize**, on the briefing's top line, keeps how you like it in this browser
221
+ only: whether the first reason opens, whether the numbers start open, which amber
222
+ reasons are hidden (a red one, failing checks or blocked, can be folded but never
223
+ hidden, and the On track line counts what is), whether an item opens in its drawer
224
+ or on its own page, and **Run Analyze after each sync**, off unless you turn it on,
225
+ since each run uses your agent's usage. It runs once for each sync that finishes
226
+ while the page is open, never for the one already there when it opened.
192
227
 
193
228
  ### The Dependencies tab
194
229
 
@@ -207,8 +242,8 @@ blocks another or is blocked, on the current sprint's dates, then the dependency
207
242
  A dashed arrow is a wait that is over: the blocker is done. A dotted line marks today.
208
243
  - **The critical chain** is the chain of open blockers holding the most points (the
209
244
  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.
245
+ its arrows are drawn heavy, and it is named above the chart. The briefing's
246
+ **Blocked** reason names the same items.
212
247
  - **What is estimated is said, in the chart's note and on each table cell.** No tracker
213
248
  toil reads dates a link, so a block is drawn from when both items existed. An item
214
249
  whose history records no move into In progress (GitHub records only open and closed)
@@ -237,8 +272,7 @@ deployments themselves.
237
272
 
238
273
  ## Insights
239
274
 
240
- The board's cards and its **Needs attention** flag, the flow charts and the Overview's
241
- key issues mark
275
+ The board's cards and its **Needs attention** flag and the flow charts mark
242
276
  each open work item with its insights, weightiest first, each naming the data it
243
277
  rests on (`ui/src/model/insights.ts`). One the data can't support isn't raised at
244
278
  all, rather than raised on a guess.
@@ -609,6 +643,12 @@ requests, builds and deployments that name them.
609
643
  `updatedAt` moved. Only those items and their histories are fetched again.
610
644
  Pull requests, builds, deployments and iterations have no "changed since" in
611
645
  toil, so they're read again each time, bounded as the dashboards bound them.
646
+ Once a day, the Jira and Azure DevOps searches are also sent whole (ids only
647
+ where toil can), and an item they no longer list is dropped; if that listing
648
+ fails, the changes are kept and the next sync tries it again. Per-item calls
649
+ (histories, pull request gets) run 4 at a time across a dossier.
650
+ Azure DevOps histories come from the project's revisions feed, read from the
651
+ watermark; an item is read on its own when the feed doesn't hold all of it.
612
652
  - **Every page.** Each call follows `meta.page.nextCursor` to the end, up to 200
613
653
  pages, and fails that source, saying so, rather than keep part of a listing.
614
654
  - **Each source on its own.** Each area a dossier reads (Jira, Bitbucket, Jenkins,
@@ -626,17 +666,25 @@ requests, builds and deployments that name them.
626
666
  ticket content, so it stays on this machine and is readable by your account
627
667
  only. The analyses (#395) are kept in the same file, the newest 100 per dossier,
628
668
  and a sync never rewrites them.
629
- - **For how long.** Anything not synced again within the retention period (30
630
- days by default) is deleted, at start and after each sync. An analysis goes once
669
+ - **For how long.** A dossier's synced data (responses, items,
670
+ transitions, change refs, worklog facts and each source's state) expires together, once the
671
+ last sync that saved data for it is older than the retention period (30 days by default),
672
+ at start and after each sync. A sync that fails doesn't keep old data alive. Worklog facts that no
673
+ sync produces any more go about 1.25 times the retention period after they were last seen. The rest
674
+ goes when it is that old itself. The retention period
675
+ also sets how far back closed Jira and Azure DevOps items are read, with a
676
+ floor of 6 weeks (see What it reads). An analysis goes once
631
677
  it is older than the retention period, and with its dossier when toil no longer
632
678
  has it.
633
679
  - **Wiping it.** **Wipe the cache** in the Sync panel deletes it after asking
634
680
  first. `toil-ui wipe` does the same from a terminal, once `toil-ui` has
635
681
  stopped: a running Toil UI holds `toil-ui.lock` in the data folder, and the
636
682
  command refuses while it does. Your trackers are never touched. The next sync fetches everything again.
637
- - **Deleted tickets.** An item deleted in its tracker stays in the cache until
638
- the retention period ends or you wipe it, since an incremental search only
639
- returns items that still exist.
683
+ - **Deleted tickets.** An item deleted in its tracker, or moved out of its
684
+ project, is dropped within a day by the whole listing a Jira or Azure DevOps
685
+ sync does once a day, since an incremental search only returns items that still
686
+ exist. So is an item closed longer ago than the read window. A GitHub issue
687
+ stays until the retention period ends or you wipe the cache.
640
688
 
641
689
  The page can run only the reads the dashboards make: `dossiers list` and `dossiers
642
690
  show`, and each area's search, history, pull request, build and deployment reads.
@@ -664,15 +712,18 @@ conversation stays, for the rest of the dossier's pages, until you reload.
664
712
  - **The wording follows the theme**: the bar's placeholder, the welcome and the status
665
713
  words are in each game theme's voice, and Plain stays neutral. The starter questions
666
714
  read the same in every theme.
667
- - **Analyze** asks for a pulse check in one press: what changed since the last Analyze
668
- (from the worklog), who is on what, what is blocked or stuck in review, the sprint's
669
- health and risks, and anything that looks off, such as a ticket marked done while its
670
- pull request is open. Every line cites its items, and follow-up questions continue
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.
715
+ - **Analyze** briefs the dossier in one press (#494). Its question comes from toil,
716
+ `toil dossiers analyze prompt <dossier> --host toil-ui`: the standard method with
717
+ the dossier's own lenses and focus (Tuning Analyze, above). It answers with a
718
+ briefing block, which the server lifts out of the answer and checks, every id in it
719
+ against what the agent's tools read: a recommendation, then the reasons, each item
720
+ with why it's there and the next step, then what changed, and anything the
721
+ dossier's focus left out. The briefing, the item drawer, the chat and the analysis
722
+ page all lay it out, with the rest of the answer as **Evidence**, folded until you
723
+ open it. An answer with no briefing block is shown as it came, and says so. With a
724
+ toil that has no `dossiers analyze prompt`, Analyze asks Toil UI's own question
725
+ instead, and the answer warns that it did. Each whole Analyze is kept in the
726
+ dossier's **Analyses** tab, and the answer links to it.
676
727
  - **Citations are chips**: in every answer, each `[[id]]` is a chip with the item's
677
728
  key, title and status, linking to its page (a pull request to its host). Hovering or
678
729
  focusing one shows its type, assignee, estimate, sprint and last update. An id the
@@ -686,6 +737,17 @@ conversation stays, for the rest of the dossier's pages, until you reload.
686
737
  from its next question, which carries the conversation so far; the default stays in
687
738
  Settings. An adapter that can't answer is listed with the reason and **Install** or
688
739
  **Fix**, never left out. Each answer names the adapter and model that wrote it.
740
+ - **Analyze remembers its agent for each dossier** (#494). A whole Analyze records the
741
+ agent it was asked of, in `<data folder>/dossier-agents.json` (an adapter name per
742
+ dossier name, Toil UI's own state, never in the dossier file). The next time the chat
743
+ opens on that dossier it starts on that agent if it can still answer, else on the
744
+ default from Settings, Agent (Claude, GitHub Copilot or Codex), else as before, with
745
+ the server trying the default and saying why it can't. A few words beside **Answered
746
+ by** say which: "last used on this dossier", "your default" or "picked for this chat".
747
+ Picking another agent and running Analyze updates the memory; a question that isn't
748
+ Analyze, or an Analyze that fails or is stopped, doesn't. Renaming a dossier moves its
749
+ memory, and a dossier toil no longer has is forgotten on the next full sync. The sample
750
+ remembers nothing.
689
751
 
690
752
  The chat answers with the agent your organization already approved, on the
691
753
  subscription you already have. Toil UI has three adapters, each an optional peer
@@ -1011,6 +1073,9 @@ it goes, both on by default:
1011
1073
  dungeon master in Realm, a laconic netrunner in Sprawl, a dry telegraph operator
1012
1074
  in Frontier, an old sage in a cave in Overworld. It changes phrasing only.
1013
1075
 
1076
+ Every theme has a light and a dark scheme. **Appearance**, in Settings, General or the
1077
+ command palette, picks one; System, the default, follows your operating system.
1078
+
1014
1079
  A theme with particles also gets **Particles and ambient effects**, kept for each
1015
1080
  theme on its own: off, that theme's particles are gone entirely, while its other
1016
1081
  motion keeps following **Reduce motion and effects** (and the operating system's
@@ -1042,8 +1107,8 @@ Any program on the machine, or a web page using DNS rebinding, can reach a local
1042
1107
  port, so the server lets in only the browser holding this launch's token:
1043
1108
 
1044
1109
  - **The token.** A random token per start, in the URL it prints. The page trades it
1045
- for a session id, which it keeps in memory and sends as a header on every API
1046
- call. Nothing is kept in a cookie: a browser would send one to any other server
1110
+ for a session id, which the tab keeps in `sessionStorage` (see Start it) and
1111
+ sends as a header on every API call. Nothing is kept in a cookie: a browser would send one to any other server
1047
1112
  on `127.0.0.1`, whatever its port.
1048
1113
  - **The Host header.** Only the exact `127.0.0.1:<port>` it printed is answered.
1049
1114
  - **No CORS.** No `Access-Control-*` header is ever sent. Every POST also needs the
@@ -1155,8 +1220,8 @@ npm run verify:ui -- --no-build --starter standup
1155
1220
  that its proposals parsed, that nothing ran (no write in toil's audit log for the
1156
1221
  run), and that `codex mcp list` in Toil UI's Codex home shows only `toil_ui`. Then it
1157
1222
  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
1223
+ (#395): that Analyze was kept with its briefing (a recommendation, and its first
1224
+ three reasons as the history's issues); then it changes the dossier's WIP limit in the scratch home (`toil dossiers
1160
1225
  wip-limit --replace`), asks Analyze again, checks the history lists both, newest
1161
1226
  first, the second compared with the first, and puts the Overview, the Analyses tab
1162
1227
  and the second analysis opened through the layout check, shot. It needs the Codex CLI signed in and the
@@ -1172,8 +1237,8 @@ npm run verify:ui -- --no-build --starter standup
1172
1237
 
1173
1238
  `--source ado` runs the real-data part against an Azure DevOps Services board
1174
1239
  instead (the `ado-board` dossier, as `dev-real.mjs --source ado` makes it below),
1175
- with `TOIL_ADO_CLOUD_BASE_URL`, `TOIL_ADO_CLOUD_PAT` and `--project <name>` (else
1176
- `TOIL_ADO_CLOUD_PROJECT`); without them it skips that part and says why. Each source is
1240
+ with `TOIL_ADO_BASE_URL`, `TOIL_ADO_PAT` and `--project <name>` (else
1241
+ `TOIL_ADO_PROJECT`); without them it skips that part and says why. Each source is
1177
1242
  one entry in `SOURCES` in `scripts/verify.mjs`. Set `CHROME_PATH` if the browser it finds doesn't draw headless; Playwright's
1178
1243
  Chromium works where an installed Chrome doesn't.
1179
1244
 
@@ -1204,19 +1269,19 @@ toil's `github` area doesn't read.
1204
1269
  ### An Azure DevOps Services board
1205
1270
 
1206
1271
  `--source ado` runs the same way against an Azure DevOps Services project, through
1207
- toil's `ado-cloud` area, with a dossier named `ado-board`:
1272
+ toil's `ado` area on a Services connection, with a dossier named `ado-board`:
1208
1273
 
1209
1274
  ```bash
1210
1275
  node ui/scripts/dev-real.mjs --source ado --project "<project>"
1211
1276
  ```
1212
1277
 
1213
- It needs `TOIL_ADO_CLOUD_BASE_URL` (`https://dev.azure.com/<organization>`) and
1214
- `TOIL_ADO_CLOUD_PAT` (an organization-scoped token with Work Items, Read) in the
1215
- shell. They go into Toil UI's environment only: toil makes its `ado-cloud`
1278
+ It needs `TOIL_ADO_BASE_URL` (`https://dev.azure.com/<organization>`) and
1279
+ `TOIL_ADO_PAT` (an organization-scoped token with Work Items, Read) in the
1280
+ shell. They go into Toil UI's environment only: toil makes its `ado` (deployment cloud)
1216
1281
  connection from them, with writes off, and nothing about the organization is
1217
- written to the config file. `--project`, or `TOIL_ADO_CLOUD_PROJECT`, names the
1282
+ written to the config file. `--project`, or `TOIL_ADO_PROJECT`, names the
1218
1283
  project; the dossier in the scratch home holds it. The dossier names no repository,
1219
- so no pull requests are read; add `repo` to its `ado-cloud` section for them.
1284
+ so no pull requests are read; add `repo` to its `ado` section for them.
1220
1285
 
1221
1286
  To fill a board with made-up work, `ui/scripts/ado-seed/` seeds one from Open Work
1222
1287
  Items. `items.owi.json` holds 45 of them across the three sample products
@@ -1249,9 +1314,9 @@ To check what toil reads back, map the board's output and compare it with the fi
1249
1314
  difference, leaving out what the server assigns.
1250
1315
 
1251
1316
  ```bash
1252
- toil ado-cloud work-item iterations --project "<project>" > board.jsonl
1253
- toil ado-cloud work-item get-many <ids…> >> board.jsonl
1254
- toil ado-cloud work-item history <id> >> board.jsonl # once for each id
1317
+ toil ado work-item iterations --project "<project>" > board.jsonl
1318
+ toil ado work-item get-many <ids…> >> board.jsonl
1319
+ toil ado work-item history <id> >> board.jsonl # once for each id
1255
1320
  toil util owi map board.jsonl > mapped.json
1256
1321
  node ui/scripts/ado-seed/compare.mjs mapped.json --project "<project>" --backdated
1257
1322
  ```
@@ -1308,7 +1373,7 @@ its table. For the same reason neither command runs in CI, and neither is part o
1308
1373
  | Port | `--port` | `TOIL_UI_PORT` | `0`: the OS picks a free one |
1309
1374
  | Base path | `--base-path` | `TOIL_UI_BASE_PATH` | `/` |
1310
1375
  | Data folder | `--data-dir` | `TOIL_UI_DATA_DIR` | `~/.toil-ui` |
1311
- | Retention | `--retention-days` | `TOIL_UI_RETENTION_DAYS` | `30` (1 to 3650) |
1376
+ | Retention | `--retention-days` | `TOIL_UI_RETENTION_DAYS` | `30` (1 to 3650); also how far back closed Jira and Azure DevOps items are read, at least 42 days |
1312
1377
 
1313
1378
  A flag beats its env var. Any bind address other than loopback is refused in this
1314
1379
  release. The data folder is Toil UI's own, apart from toil's `~/.toil/`, and holds