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

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
@@ -1,14 +1,14 @@
1
1
  # Toil UI
2
2
 
3
3
  A local web app for seeing work across Jira, Azure DevOps and GitHub, read through
4
- [toil](https://www.npmjs.com/package/@imagile-dev/toil): one dashboard per dossier,
4
+ [toil](https://www.npmjs.com/package/@imagile-dev/toil): one dashboard per Toil project,
5
5
  with its stories, pull requests, builds and deployments side by side, a pull
6
6
  requests view for what is waiting on review, and a daily worklog of what happened.
7
7
 
8
8
  **Status: beta, local only.** It runs on your own machine, binds loopback, and
9
- reads through toil with your own connections and dossiers, read-only. Its
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
9
+ reads through toil with your own connections and Toil projects, read-only. Its
10
+ settings pages, and a Toil project'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 Toil projects. The worklog keeps its pages and the notes you add in its own
12
12
  data folder, and writes anywhere else only when you export a page. Its Feedback dialog sends a report to Imagile through
13
13
  `toil feedback`, only when you approve it. It is a separate package from toil: installing toil
14
14
  never installs it. toil's beta commitment to stable commands, flags and output doesn't
@@ -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,160 +35,235 @@ 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
39
- Syncing through toil, read-only, with your own connections and dossiers. Only its Settings pages, and a dossier's name and description edited in place, change anything: toil's own connections and dossiers, when you ask. The worklog keeps its pages and your notes in its data folder, and writes anywhere else only when you export one. Feedback goes to Imagile only when you send it.
38
+ Toil UI <version> (beta, local only), on toil <version>
39
+ Syncing through toil, read-only, with your own connections and Toil projects. Only its Settings pages, and a Toil project's name and description edited in place, change anything: toil's own connections and toilProjects, 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
 
42
42
  Open this URL in your browser. It carries this launch's token, so keep it to yourself:
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.
50
51
 
51
- `toil-ui --sample` serves the sample dossiers and the scripted agent that
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.
58
+
59
+ `toil-ui --sample` serves the sample Toil projects and the scripted agent that
52
60
  [the site's Toil UI page](https://imagile-dev.github.io/toil/ui/) runs on, with
53
61
  nothing connected to a tracker.
54
62
 
55
63
  ## First run
56
64
 
57
- Until you have a dossier and it has synced once, the Dossiers view shows a short
65
+ Until you have a Toil project and it has synced once, the Toil projects 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.
61
- 2. **Create a dossier** opens Settings, Dossiers at Create a dossier.
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.
69
+ 2. **Create a Toil project** opens Settings, Toil projects at Create a Toil project.
62
70
  3. **Sync** starts the first sync, as the Sync panel's Sync now does.
63
71
 
64
72
  Each step ticks itself off from toil's own state: `toil connections list` for a
65
73
  connection to Jira, Azure DevOps or GitHub (one made by env vars counts), `toil
66
- dossiers list` for a dossier, and the Sync panel for the sync. Beside the steps,
74
+ projects list` for a Toil project, and the Sync panel for the sync. Beside the steps,
67
75
  **Try the sample data** shows `npx @imagile-dev/toil-ui --sample` with a Copy
68
- button, to restart Toil UI on the sample dossiers. The checklist goes once the first
76
+ button, to restart Toil UI on the sample Toil projects. The checklist goes once the first
69
77
  sync finishes. Each step's (i) explains it and links to these docs.
70
78
 
71
79
  ## What it reads
72
80
 
73
- Each dashboard reads its dossier the way `toil dossiers show` describes it: the
74
- Jira project, the Azure DevOps project and pipelines, the GitHub repository and
75
- project board, and the OpenShift namespace of each environment. A GitHub section
76
- with no `projects` reads the repository's own issues, open and closed, as its work
77
- items, with the history of every open one and the 50 most recently closed. Pull
78
- requests are read from every code host the dossier names (GitHub, Bitbucket Data
81
+ Each dashboard reads its Toil project the way `toil projects show` describes it: the
82
+ Jira project, the Azure DevOps project and pipelines, the GitHub repositories and
83
+ project board, and the OpenShift namespace of each environment. A Toil project's GitHub
84
+ repositories are the `github` section's `owner` and `repo` (one value, or one per repo
85
+ name), plus its `repos` remotes on github.com or on the host of a repository the section names, and each is read on its own
86
+ with `owner` and `repo` passed explicitly (`src/github-repos.ts`); a repository that
87
+ couldn't be read gets one muted line where its gap shows: "pull requests not read" on the Pull requests view (linking to the failed call), "work items not read" on the Board tab. The same goes for the other
88
+ areas' per-repo values: a Jira `project`, a Bitbucket `project`, `workspace` or `repo`,
89
+ and an Azure DevOps `collection`, `project` or `repo` given as an object of repo name to
90
+ value are each read once per target (one Jira search per project, work items per Azure
91
+ DevOps project, pull requests per repo) with those inputs passed explicitly
92
+ (`src/targets.ts`; a pipeline is tried in each Azure DevOps project in turn, and a repo name the section leaves half-named is shown as not read), because Toil UI has no repo folder for toil to pick one from; a section
93
+ with plain values sends the calls it always did. Only GitHub's remotes are read for more
94
+ targets. A GitHub section with no `projects`
95
+ reads each repository's own issues, open and closed, as its work items, with the
96
+ history of every open one and the 50 most recently closed in each. Pull
97
+ requests are read from every code host the Toil project names (GitHub, Bitbucket Data
79
98
  Center and Cloud, Azure DevOps Server and Services) with `pr list`, then `pr get
80
99
  --include reviews,checks,commits,files` for every open one and the 20 newest closed or
81
- merged ones, and mapped to OWI 0.2 changes; a GitHub repository's CODEOWNERS is read
100
+ merged ones (of each GitHub repository), and mapped to OWI 0.2 changes; a GitHub repository's CODEOWNERS is read
82
101
  with `github repo file` when an open pull request has no reviewer. Every call runs
83
102
  in-process through `@imagile-dev/toil/api`, read-only, and toil's audit log
84
103
  records it with `via: "api"` and `caller: "toil-ui"`. A call that fails shows on
85
104
  its own panel with toil's message and fix.
86
105
 
87
- ## The Dossiers view
106
+ Jira and Azure DevOps are read for their open items plus anything changed within
107
+ the read window: the retention period, but at least 6 weeks (42 days), so the
108
+ longest view stays whole. A closed item older than that isn't read, and so isn't
109
+ in any view.
110
+
111
+ ## Plain words
112
+
113
+ Screens read in everyday words by default: a pull request is a **code review**, an agent an **AI helper**, with toil's own term in the hover. Facts, numbers, commands and errors read the same either way. **Settings, General** (and the command palette) turn it off, kept in this browser; `?words=standard` in the address does too. Themed wording and themed agent voice are off until chosen.
114
+
115
+ The tabs read **Summary**, **Board**, **What blocks what** (Dependencies), **Code reviews**, **People**, **What happened** (Worklog) and **Past briefings** (Analyses); Analyze is **Get a briefing**. A panel's source reads "From Jira and GitHub", with the commands one step in. **Settings → General** has a **Plain words** switch with an (i), and the command palette has **Use plain words** / **Use toil's own terms**. Quoted titles, the tracker's words and a briefing's own sentences are never reworded.
116
+
117
+ ## The Toil projects view
88
118
 
89
- Toil UI opens on its dossiers, one card each, read from the same data the dashboards
119
+ Toil UI opens on its Toil projects, one card each, read from the same data the dashboards
90
120
  read, so it asks no tracker anything: in the local app that is the cache a sync
91
- filled, plus `dossiers list` and `dossiers show` for the dossiers themselves.
121
+ filled, plus `projects list` and `projects show` for the Toil projects themselves.
92
122
 
93
123
  - **What each card shows:** the current sprint with its working days left, points
94
124
  done and a small burn-up; how many items are in progress and blocked, and how many
95
125
  pull requests wait on a review; the people with work in it, as avatars; its sources
96
126
  as badges; when it was last synced; and how many work items and pull requests
97
127
  changed since this browser last opened its dashboard.
98
- - **Which card leads:** the dossier opened most recently in this browser, or, before
128
+ - **Which card leads:** the Toil project opened most recently in this browser, or, before
99
129
  any was opened, the one with the most in motion (in progress, blocked and waiting on
100
130
  review together), takes two columns where they fit. On a wide screen the grid goes
101
131
  wider than the dashboards and fits more cards across; at 375px it is one column.
102
132
  - **What this browser remembers:** when each dashboard was last opened, in
103
133
  `localStorage`, never sent anywhere. Without it (a private window) the cards just
104
134
  say nothing about "since".
105
- - **A dossier's top row** uses the same parts: the description beside the name, the
106
- sources as badges, and the sprint's day (The dossier page, below).
135
+ - **A Toil project's top row** uses the same parts: the description beside the name, the
136
+ sources as badges, and the sprint's day (The Toil project page, below).
107
137
 
108
- ### Renaming and describing a dossier
138
+ ### Renaming and describing a Toil project
109
139
 
110
140
  The name and the description have a pencil beside them, on the card and in the
111
- dossier's top row. It opens an inline field: Enter saves through
112
- `toil dossiers describe <dossier> --name <new name>` or `--description <text>`, run
141
+ Toil project's top row. It opens an inline field: Enter saves through
142
+ `toil projects describe <toilProject> --name <new name>` or `--description <text>`, run
113
143
  on the settings pages' path (below), so toil's own checks apply and the change is in
114
144
  its audit log as `caller: "toil-ui"`. Escape cancels, and a refusal shows toil's
115
- message and fix under the field. Only a dossier in your own folder can be renamed or
116
- described; a checked-in one is refused with the `toil dossiers import` fix.
145
+ message and fix under the field. Only a Toil project in your own folder can be renamed or
146
+ described; a checked-in one is refused with the `toil projects import` fix.
117
147
 
118
- A rename keeps everything Toil UI holds for the dossier: the server moves its cache
148
+ A rename keeps everything Toil UI holds for the Toil project: the server moves its cache
119
149
  (responses, items, history, sources, sync runs, notes and agent runs), its assignments
120
150
  and its worklog pages to the new name once toil has renamed the file, so its
121
151
  dashboard opens straight away with no new sync. A rename waits, refused with a
122
- message, while a sync or an assignment of that dossier is running, since both read it
152
+ message, while a sync or an assignment of that Toil project is running, since both read it
123
153
  by name as they go. What can't be moved is said beside toil's result, and the next
124
- sync reads the dossier afresh under its new name.
154
+ sync reads the Toil project afresh under its new name.
125
155
 
126
- ## The dossier page
156
+ ## The Toil project page
127
157
 
128
- A dossier opens on its **Overview**, in a frame all of its pages share:
158
+ A Toil project opens on its **Overview**, the briefing, in a frame all of its pages share:
129
159
 
130
- - **The top row:** its name, with the pencil that renames it; **Switch**, for another
131
- dossier or the Dossiers view; the sprint and its day; its description, cut to one
132
- line with the whole of it in its tooltip, and its sources; and the Ask bar with
133
- **Analyze** (The agent, below).
134
- - **The tabs**, one address each: **Overview** (`#/dossier/<name>`), **Board**
160
+ - **The top row:** on the Overview, a **Diagram** link (`#/project/<name>/job/diagram`) draws the Toil project's repositories as a C4 diagram in Mermaid; the steps that need a folder on disk (`util size`, `git log`, `deps scan`) are reported unchecked. Its name, with the pencil that renames it; **Switch**, for another
161
+ Toil project or the Toil projects view; the sprint and its day; its description, cut to one
162
+ line with the whole of it in its tooltip, and its sources (on a phone, a **Details** button beside the name opens them); and the Ask bar, with the
163
+ **AI helpers** button beside it (The agent, below).
164
+ - **The tabs**, one address each: **Overview** (`#/project/<name>`), **Board**
135
165
  (`/board`, with how many of its cards need attention), **Dependencies**
136
166
  (`/dependencies`), **Pull requests** (`/prs`), **People** (`/people`), **Worklog**
137
167
  (`/worklog`) and **Analyses** (`/analyses`). The Command Center (`/command-center`)
138
168
  is the Board tab's **Readiness** view, the stand-up is the Worklog's, and an item's
139
169
  page sits under Board, so every address from before the tabs still opens. On a
140
- narrow screen the tabs scroll sideways.
141
- - **The Agents sidebar**, beside every tab from 1200px wide, and a drawer behind the
142
- **Agents** button below that: the tracker's inbox, then the dossier's assignments
170
+ narrow screen the tabs scroll sideways; the Agents button sits beside the Ask bar at
171
+ every width (a compact **AI** with its count on a phone, still named "AI helpers"), so the tabs get the whole row.
172
+ - **The Agents panel**, closed by default at every width: one **Agents** button (**AI helpers** in plain words)
173
+ beside the Ask bar, counting what waits on you (the tracker's inbox, proposals to approve and
174
+ questions to answer, and any assignment or proposal that failed, since a closed panel must not hide a failure). From 1200px wide it opens the panel beside every tab, and remembers
175
+ whether you left it open (in `localStorage`); below that it opens a drawer. The palette's
176
+ **Open the Agents panel** does the same. It holds: the tracker's inbox, then the Toil project's assignments
143
177
  in three groups (those that need you, those working, and those gone stale), with the
144
178
  finished ones under **Earlier**; then **Renew all stale**, the **Limits**, and this
145
- dossier's three newest analyses, each linking to it (Assigning work to an agent, below).
146
- - **Analyses** lists every Analyze kept for the dossier, newest first: when it was made,
179
+ Toil project's three newest analyses, each linking to it (Assigning work to an agent, below). Each card's title is its link; how many run at once, for how long, and what the inbox is are in the heading's (i), and the tracker's raw label (`agent:refine`) is in the Start dialog.
180
+ While an item's drawer is open (`?item=<id>`, The briefing, below), it takes the
181
+ sidebar's column from 1200px wide, and covers the view from the right below that.
182
+ - **Analyses** lists every Analyze kept for the Toil project, newest first: when it was made,
147
183
  the adapter and model that wrote it, its one-line recommendation, and what changed
148
184
  since the one before (items newly blocked or blocked by something new, blockers
149
185
  cleared, points moved on an item or in the sprint, items newly cited or no longer
150
186
  cited, a new recommendation). What changed is worked out by code, from a snapshot of
151
- the dossier's items each analysis keeps, never by asking the agent. **Open** reads one
187
+ the Toil project's items each analysis keeps, never by asking the agent. **Open** reads one
152
188
  again at its own address (`/analyses/<id>`), top-down like the chat, with its
153
189
  suggested changes and what it used. The server keeps them in the cache (Sync and the
154
190
  cache, below), so they outlast a reload and a restart; with `--sample`,
155
191
  card-payments starts with two, kept in memory for the run.
156
192
 
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.
193
+ ### The briefing
194
+
195
+ A Toil project opens on its briefing: one column to read top to bottom, each part a step
196
+ further in, and each step one you choose (#494). The tab's top is the answer (#552):
197
+
198
+ - **The status sentence**, the biggest text on the tab: a word with a shape (On
199
+ track, At risk, Behind, No sprint, or No estimates when no story in the sprint has points) and the rest of the sentence ("Behind: 18 of
200
+ 21 points are left, and 3 working days remain."), with an (i). That it is an estimate is the first line of the fold; "Too early in the sprint to judge a pace" stays on the page. One rule
201
+ picks the word (`ui/src/model/status.ts`): On track when the points left fit at
202
+ the pace so far, At risk when at least 75% of them would land or a red reason holds
203
+ work up, Behind below 75%; the fold says 75% is the app's own rule of thumb. Today isn't counted in the working days left, as on the
204
+ Toil project cards.
205
+ - **One line on why**, from the briefing on screen, naming items by their titles (quoted as they are, never reworded by plain words), and
206
+ **How was this worked out?** one step in, with the sums and the rule.
207
+ - **Needs attention**, at most three cards, the same for everyone: the biggest risk,
208
+ stories that can't start, the oldest code review waiting past the pickup limit;
209
+ stories not ready to start take the place of an empty one, and an all-clear card
210
+ says so when nothing needs anyone; if a read failed, that card says which reads could not be read instead of an all-clear. A card's title is its one link, opening the item in
211
+ its drawer (or its page, as Customize says), with the ticket key in small print.
212
+ - **Outside the fold, too:** one compact line for each red reason no card already tells (it opens the reason in the fold), and the "Couldn't check" line for a panel that could not be read.
213
+ - **Show the full briefing**, closed until you open it, and remembered in this
214
+ browser: everything below, with Customize. The source and sprint line, any problem
215
+ with the briefing, and **Go to** stay in view outside it.
216
+
217
+ 1. **The recommendation:** the one thing to do first, as a sentence. The sprint and
218
+ its day, and who wrote the briefing, stay under the answer, outside the fold: the latest Analyze, when it is
219
+ current (made since the data was read, or the same UTC day) and answered with a
220
+ briefing, with who wrote it, when, and a link to it; otherwise toil's briefing by
221
+ code (`toil projects brief`, `src/core/brief/`), with no agent call, which says so,
222
+ and why when an older Analyze exists.
223
+ 2. **Why:** the reasons, one line each, the first open and the rest folded: Failing
224
+ checks, Blocked, Waiting on review, Sprint at risk, Stale, Over the WIP limit, and
225
+ Ticket and pull request disagree, in the Toil project's order. Each item is under one
226
+ reason only, as a row with its key, title and assignee. Then **On track**, counted
227
+ rather than listed.
228
+ 3. **One step in:** anything the Toil project's focus left out, with why, and anything the
229
+ code flagged that Analyze didn't mention, so nothing drops off the page unsaid. An
230
+ id Analyze named that isn't the Toil project's is shown in red.
231
+ 4. **The numbers**, folded: burn-up, throughput, cycle time, aging work in progress
232
+ and pull request wait, each opening its full chart.
233
+ 5. **Go to:** every other view, as well as its tab.
234
+
235
+ A row, or any item link on the briefing, opens the item's **drawer** at the page's
236
+ own address plus `?item=<id>`: beside the view at 1200px and wider, over it below
237
+ that. It says why the item is there and who said so, the next step when Analyze
238
+ wrote one, any change Analyze proposed for it, its pull requests and the chain it's
239
+ in, with **Open** for its page and a link to it in its tracker. A Board card's key
240
+ and the items on Pull requests open the same drawer. Escape or **Close** goes back
241
+ to the view behind it.
242
+
243
+ #### Tuning Analyze
244
+
245
+ Each Toil project tunes how Analyze briefs it, under **Settings → Toil projects**, **How
246
+ Analyze briefs** (`#/settings/projects/<name>/analyze`): its goal, who it's written
247
+ for, its lenses in order with their thresholds, and what else to watch for or leave
248
+ out, the lenses folded until you open them. **The prompt Analyze will send**, under
249
+ the form, shows it as you type, composed by toil's own code, and **Save** runs
250
+ `toil projects analyze set` with only what you changed, the line it runs shown under
251
+ the form. The settings live in the Toil project file, so a team that shares the Toil project
252
+ shares them; whenever a Toil project tunes Analyze, the briefing names the file and
253
+ whether it's your own, and a focus from a Toil project you haven't adopted still applies.
254
+ Clearing a setting is a delete, made in a terminal. Toil UI composes the preview with
255
+ the toil code it's built with, and Analyze asks the toil it runs on, so the two match
256
+ when Toil UI and toil are released together.
257
+
258
+ #### Customize
259
+
260
+ **Customize**, on the briefing's top line, keeps how you like it in this browser
261
+ only: whether the first reason opens, whether the numbers start open, which amber
262
+ reasons are hidden (a red one, failing checks or blocked, can be folded but never
263
+ hidden, and the On track line counts what is), whether an item opens in its drawer
264
+ or on its own page, and **Run Analyze after each sync**, off unless you turn it on,
265
+ since each run uses your agent's usage. It runs once for each sync that finishes
266
+ while the page is open, never for the one already there when it opened.
192
267
 
193
268
  ### The Dependencies tab
194
269
 
@@ -207,13 +282,13 @@ blocks another or is blocked, on the current sprint's dates, then the dependency
207
282
  A dashed arrow is a wait that is over: the blocker is done. A dotted line marks today.
208
283
  - **The critical chain** is the chain of open blockers holding the most points (the
209
284
  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.
285
+ its arrows are drawn heavy, and it is named above the chart. The briefing's
286
+ **Blocked** reason names the same items.
212
287
  - **What is estimated is said, in the chart's note and on each table cell.** No tracker
213
288
  toil reads dates a link, so a block is drawn from when both items existed. An item
214
289
  whose history records no move into In progress (GitHub records only open and closed)
215
290
  is drawn in progress from when it was created. Nothing is fetched for the chart: it
216
- reads the links, transitions, pull requests, builds and checks the dossier already
291
+ reads the links, transitions, pull requests, builds and checks the Toil project already
217
292
  synced, and the readiness gate's verdict for work not started.
218
293
  - **The table under the chart lists every bar and every arrow**, with links: each
219
294
  item's status and points, its time in progress, blocked (and by what) and with
@@ -237,29 +312,30 @@ deployments themselves.
237
312
 
238
313
  ## Insights
239
314
 
240
- The board's cards and its **Needs attention** flag, the flow charts and the Overview's
241
- key issues mark
315
+ The board's cards and its **Needs attention** flag and the flow charts mark
242
316
  each open work item with its insights, weightiest first, each naming the data it
243
317
  rests on (`ui/src/model/insights.ts`). One the data can't support isn't raised at
244
- all, rather than raised on a guess.
318
+ all, rather than raised on a guess. A card shows one chip per kind of insight,
319
+ with a count when there are several ("Blocking 2"); its tooltip lists each one,
320
+ and the item view lists them all.
245
321
 
246
322
  | Insight | Means | Weight |
247
323
  |---|---|---|
248
324
  | Blocked | Another item that isn't done blocks it (its links) | needs action now |
249
325
  | Build failing | Its pull request's latest build failed | needs action now |
250
- | 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 |
326
+ | Aging | In progress longer than 85% of the Toil project's finished items took; needs at least three cycle times to compare with | needs action now |
251
327
  | Deployed, still open | An environment runs it, but it isn't done | needs a look |
252
328
  | Carried over | It was in the previous sprint too | needs a look |
253
329
  | PR with no build | A pull request for it is open with no build | needs a look |
254
330
  | Stale | No update for more than 5 days | needs a look |
255
331
  | Blocking | It blocks another item | needs a look |
256
- | Merged, not deployed | Its pull requests are merged, but no environment runs them yet; only for a dossier that names environments | worth knowing |
332
+ | Merged, not deployed | Its pull requests are merged, but no environment runs them yet; only for a Toil project that names environments | worth knowing |
257
333
  | No estimate | It has no estimate | worth knowing |
258
334
  | Added mid-sprint | It joined the sprint after it started | worth knowing |
259
335
 
260
336
  ## Pull requests
261
337
 
262
- Each dossier has a **Pull requests** tab (`#/dossier/<name>/prs`), built from OWI 0.2
338
+ Each Toil project has a **Pull requests** tab (`#/project/<name>/prs`), built from OWI 0.2
263
339
  changes:
264
340
 
265
341
  - **Waiting now:** the open pull requests, longest wait first, each with what it
@@ -273,35 +349,36 @@ changes:
273
349
  merge (approval to merge) times, review rounds, sizes and merges per week, over six
274
350
  weeks, each split by people, agents and bots and each with its sample size and what
275
351
  couldn't be measured.
352
+ - **Actions:** each open pull request has one **Actions** menu with **Review** (reads the pull request, its diff and checks, and drafts findings as comments you can post) and **Ship** (on a pull request a person wrote: drafts replies to its review; editing, the gate and pushing stay in your terminal). Each opens its own page, `#/project/<name>/job/review?target=<change id>` or `/job/ship?…`, which says what the job does and needs and has **Run**. The run goes through the Ask bar, so every write is a proposal card and the run is kept in the worklog. A job missing its code host's connection stays in the menu, dimmed, naming the connection to add. Ship stops after 3 finished rounds on one pull request; the next run is refused and says it needs a person (`needs-human`). The steps come from toil's workflow pages (`skills/toil/workflows/`).
276
353
  - **Suggested reviewers:** for an open pull request with nobody asked, the CODEOWNERS
277
354
  of its paths and the earlier reviewers of the same files and folders, each as a
278
355
  proposal with the `toil … --allow-write` line to ask them.
279
356
 
280
- The dossier's work item keys are matched in each pull request's title, branch and
357
+ The Toil project's work item keys are matched in each pull request's title, branch and
281
358
  description (a Jira project's `PAY-101`, Azure Boards' `AB#2302`, a GitHub
282
359
  repository's `owner/repo#41`). A code host's section may set author kinds by hand,
283
360
  `"authorKinds": { "release-bot": "BOT" }`, which win over every other signal.
284
361
 
285
362
  ## People
286
363
 
287
- Each dossier has a **People** tab (`#/dossier/<name>/people`), built
364
+ Each Toil project has a **People** tab (`#/project/<name>/people`), built
288
365
  from the same OWI work items and changes as the dashboard and the pull requests view,
289
- and from the dossier's `people` section, which says who each person is in every
290
- system (`toil dossiers person`, or **Settings, Dossiers**):
366
+ and from the Toil project's `people` section, which says who each person is in every
367
+ system (`toil projects person`, or **Settings, Toil projects**):
291
368
 
292
369
  - **A card per person**, agents included, in name order: their work in progress by
293
370
  status with how long each item has sat in it, their open pull requests and what
294
371
  each waits on, the reviews waiting on them (oldest first), their blocked items and
295
372
  what blocks each, and what they did in the last 14 days. A link opens their items
296
373
  on the Board tab, filtered to them.
297
- - **A team strip:** work in progress against the dossier's `wipLimit` and who is over
374
+ - **A team strip:** work in progress against the Toil project's `wipLimit` and who is over
298
375
  it, the review queue, and the current sprint's unassigned items.
299
376
  - **Agents:** a person with `kind: "agent"`, matched by the same signals as a pull
300
377
  request's author kind (its account, a Co-Authored-By trailer, a branch prefix) where
301
378
  the signal names it. A person's own pull request written with an agent says so.
302
- - **Accounts the dossier doesn't map** get cards of their own, so no work goes
379
+ - **Accounts the Toil project doesn't map** get cards of their own, so no work goes
303
380
  missing. One that shares an email with a person, or with an account in another
304
- system, is suggested as a match with the `toil dossiers person` line that applies
381
+ system, is suggested as a match with the `toil projects person` line that applies
305
382
  it; it is applied only when someone presses the button, and an email that fits more
306
383
  than one candidate suggests nothing and says why. Accounts that only wrote bots'
307
384
  pull requests are left out and counted.
@@ -314,20 +391,20 @@ stay team-level, in the pull requests view.
314
391
 
315
392
  Before a work item goes to an agent, Toil UI checks whether it is ready for one. The
316
393
  check uses no model and no premium request: only the item's cached OWI record, the
317
- dossier's other items, and at most one live read, made when you press for it
394
+ Toil project's other items, and at most one live read, made when you press for it
318
395
  (`ui/src/model/readiness.ts`). Its verdict is **ready**, **thin** or **blocked**, with
319
396
  one row per check:
320
397
 
321
398
  | Check | Passes when | Otherwise |
322
399
  |---|---|---|
323
- | 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 |
324
- | 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 |
325
- | 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 |
326
- | Blockers | No open item blocks it | blocked by an open item; thin for a blocker the dossier doesn't hold |
327
- | 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 |
400
+ | Acceptance criteria | The field the Toil project 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 |
401
+ | Description | At least `minWords` words (25 by default) of real text, not counting the Toil project's template lines, placeholder lines (TBD, N/A, lorem ipsum) or unfilled `<slots>` | thin |
402
+ | 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 Toil project 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 |
403
+ | Blockers | No open item blocks it | blocked by an open item; thin for a blocker the Toil project doesn't hold |
404
+ | Scope | It comes from one of the Toil project's sources, and the Toil project names a repository | blocked from outside the Toil project; thin with no repository |
328
405
 
329
406
  The verdict is blocked when any row is, thin when any row is, and ready only when every
330
- row passes. Each area's section in the dossier sets it up:
407
+ row passes. Each area's section in the Toil project sets it up:
331
408
 
332
409
  ```json
333
410
  "jira": {
@@ -344,10 +421,10 @@ that names none uses `Microsoft.VSTS.Common.AcceptanceCriteria`.
344
421
  rows, each with where its answer came from. **Check the workflow live** makes the one
345
422
  live read, read-only: `jira issue transitions` for a Jira issue, `ado work-item
346
423
  states` for an Azure DevOps type. A GitHub issue needs none.
347
- - **The Command Center** (`#/dossier/<name>/command-center`, the Board tab's Readiness view) lists every
424
+ - **The Command Center** (`#/project/<name>/command-center`, the Board tab's Readiness view) lists every
348
425
  work item with its verdict and, for each one that isn't ready, the rows that say why.
349
426
  It filters by verdict, status, type, assignee and source, and makes no live read.
350
- It is strict: only ready items are slated, in the dossier's order, under a plan id
427
+ It is strict: only ready items are slated, in the Toil project's order, under a plan id
351
428
  that changes when anything in the plan does.
352
429
  - **Starting the plan comes with assign-to-agent (#293).** Until then the start button
353
430
  is disabled and says so; the plan it would start is shown above it.
@@ -355,10 +432,10 @@ that names none uses `Microsoft.VSTS.Common.AcceptanceCriteria`.
355
432
  are ready for an agent?" (The agent, below).
356
433
  ## Worklog
357
434
 
358
- Each dossier has a **Worklog** tab (`#/dossier/<name>/worklog`):
435
+ Each Toil project has a **Worklog** tab (`#/project/<name>/worklog`):
359
436
  one page a day, folded by code from what the cache holds, facts only. No model writes
360
437
  a line of it. A calendar shows the days that have a page, with how many lines each
361
- has; a day opens as `#/dossier/<name>/worklog/<yyyy-mm-dd>`. Days and times are UTC,
438
+ has; a day opens as `#/project/<name>/worklog/<yyyy-mm-dd>`. Days and times are UTC,
362
439
  as everywhere else in Toil UI.
363
440
 
364
441
  A page has:
@@ -401,8 +478,8 @@ page is folded again from the cache and written where its text changed, as Markd
401
478
  in the data folder:
402
479
 
403
480
  ```text
404
- <data folder>/cache/worklog/<dossier>/<yyyy-mm>/<yyyy-mm-dd>.md
405
- <data folder>/cache/worklog/<dossier>/runs/<run id>.md
481
+ <data folder>/cache/worklog/<toilProject>/<yyyy-mm>/<yyyy-mm-dd>.md
482
+ <data folder>/cache/worklog/<toilProject>/runs/<run id>.md
406
483
  ```
407
484
 
408
485
  The pages live under the cache's retention: a day whose rows are gone loses its page,
@@ -413,16 +490,16 @@ it came out the same as the page kept; the same cache always gives the same page
413
490
  toil's own file service: `toil util encode base64 --decode --out <file>`, run with that
414
491
  folder as its workspace, which writes a new file only and never into toil's own
415
492
  config. Publishing an exported page is a proposal: `toil confluence page create
416
- --body-file <file> --markdown` in the dossier's Confluence space, or `toil github issue
493
+ --body-file <file> --markdown` in the Toil project's Confluence space, or `toil github issue
417
494
  create --body-file <file>` in its repository, for you to run through toil's write gate.
418
495
  Toil UI posts nothing. With sample data, notes and export are off.
419
496
 
420
497
  ### Stand-up
421
498
 
422
499
  **Stand-up since the last working day**, on the Worklog
423
- (`#/dossier/<name>/worklog/standup`), reshapes the worklog for a meeting: since the last
500
+ (`#/project/<name>/worklog/standup`), reshapes the worklog for a meeting: since the last
424
501
  working day through today (Friday through Monday on a Monday), or any range of up to 31
425
- days you pick (`#/dossier/<name>/worklog/standup/<from>/<to>`, or `/<day>` for one), and each day's page has a
502
+ days you pick (`#/project/<name>/worklog/standup/<from>/<to>`, or `/<day>` for one), and each day's page has a
426
503
  **Stand-up for this day**. It is a fold of those days' pages by code, with no model, so the
427
504
  same days always give the same report.
428
505
 
@@ -434,9 +511,9 @@ same days always give the same report.
434
511
  failed build of their pull request, a pull request of theirs waiting on review for 2
435
512
  working days or more) and **Next** (current-sprint items assigned to them and not
436
513
  started). A line belongs to whoever the fact names: who moved the item, who wrote or
437
- reviewed the pull request. A pull request a dossier agent wrote goes under the agent.
438
- - **People** come from the dossier's `people`, so one person's Jira, Azure DevOps and
439
- GitHub accounts land under one name. An account the dossier doesn't map gets its own
514
+ reviewed the pull request. A pull request a Toil project agent wrote goes under the agent.
515
+ - **People** come from the Toil project's `people`, so one person's Jira, Azure DevOps and
516
+ GitHub accounts land under one name. An account the Toil project doesn't map gets its own
440
517
  card, named with its area and id; the People view suggests where it belongs.
441
518
  - **What the worklog can't vouch for** in the range is said at the top. Review waits, the
442
519
  sprint and Next aren't on any worklog page, so they are as of the latest sync, and the
@@ -445,7 +522,7 @@ same days always give the same report.
445
522
 
446
523
  It copies as **Markdown** (for Slack, Teams or a wiki) or **plain text**, line for line as
447
524
  shown. **Export** writes the Markdown through toil's file service, as a page's export does,
448
- to `standup-<dossier>-<from>-to-<to>.md`, and publishing it to Confluence or GitHub is a
525
+ to `standup-<toilProject>-<from>-to-<to>.md`, and publishing it to Confluence or GitHub is a
449
526
  proposal for you to run.
450
527
 
451
528
  **Write it up** is optional: it asks the agent for a short narrative of the same report,
@@ -456,7 +533,7 @@ usage counts like any chat's.
456
533
 
457
534
  ## Toil's configuration
458
535
 
459
- The Settings pages manage what `toil connections` and `toil dossiers` manage, by
536
+ The Settings pages manage what `toil connections` and `toil projects` manage, by
460
537
  running those commands through `@imagile-dev/toil/api`, never by editing a file:
461
538
 
462
539
  - **Connections:** list, add, test, set the default, turn writes on or off,
@@ -471,9 +548,9 @@ running those commands through `@imagile-dev/toil/api`, never by editing a file:
471
548
  Turning writes on asks you to type the connection's name, as the CLI does. A
472
549
  connection made by `TOIL_*` env vars alone is shown read-only, with where it
473
550
  came from.
474
- - **Dossiers:** create one, add a repository, link an area, name a field, and
475
- show and check any of them. A dossier's name and description are edited in place
476
- on its card and dashboard, through `toil dossiers describe`. A link to a connection with writes on is refused
551
+ - **Toil projects:** create one, add a repository, link an area, name a field, and
552
+ show and check any of them. A Toil project's name and description are edited in place
553
+ on its card and dashboard, through `toil projects describe`. A link to a connection with writes on is refused
477
554
  here, as over MCP: make it on the CLI.
478
555
  - **Bounds and time limit:** toil has no command for these, so they are shown
479
556
  read-only, with the file or env var that sets them.
@@ -495,7 +572,7 @@ newer than 0.1.0-alpha.2; with that one, use the CLI.
495
572
  An **(i)** beside a term explains it in a sentence or two when you hover or focus
496
573
  it, and pressing it opens the same words with a **Read more** link to the section
497
574
  of these docs that says the rest. A **pencil** beside a configurable value (a
498
- connection, a dossier's sources, people, field names or work-in-progress limit,
575
+ connection, a Toil project's sources, people, field names or work-in-progress limit,
499
576
  the agent, a usage cap) opens the settings page where it's set, at that value; it
500
577
  only navigates. **Help** in the header is a menu with the docs for the view you're on
501
578
  and **What's new** (below).
@@ -506,7 +583,7 @@ dialog's modes, session and system prompt in Renew all stale, hallucination in t
506
583
  chat's **About these answers**), its (i) popover also gives each term's first
507
584
  sentence from Context Overflow's glossary, with **Read more on Context Overflow**.
508
585
  Help's menu then has **Learn**: four of Context Overflow's modules, by task.
509
- The agent's empty chat has the same **Learn**. **Links to learning content**, under
586
+ **Links to learning content**, under
510
587
  **Settings, General** and kept in this browser, is on by default; off, every link to
511
588
  Context Overflow and every glossary line is gone, and Help keeps the view's docs and
512
589
  What's new.
@@ -520,12 +597,12 @@ views follow.
520
597
 
521
598
  Every empty panel offers the one action that fills it, under one short line, with any
522
599
  explanation in its (i): **Link a pipeline** and **Add an environment** (pencils to
523
- Dossier setup at the dossier's sources) on the Board tab's builds and deployments, **Add
600
+ Toil project setup at the Toil project's sources) on the Board tab's builds and deployments, **Add
524
601
  a repository** for pull requests, **Add a person** on the People tab, **Analyze now**
525
602
  for an empty Analyses tab, **Show every item** for a Command Center filter that hides
526
603
  everything, and **Sync now** in the local app wherever only a newer read of the tracker
527
604
  fills the panel (the sprint, the burn-up, links between items). The site preview can't
528
- sync, so it offers Dossier setup there instead. A test fails on any empty panel with
605
+ sync, so it offers Toil project setup there instead. A test fails on any empty panel with
529
606
  neither an action nor a link.
530
607
 
531
608
  ### What's new
@@ -546,23 +623,23 @@ screen it's **Search and commands** in the header's Menu. Type to narrow it down
546
623
  use the arrow keys to move, **Enter** to open and **Escape** to close. It's hidden
547
624
  until you call it up.
548
625
 
549
- - **Jump** to a dossier, any of a dossier's tabs (Overview, Board, Dependencies,
626
+ - **Jump** to a Toil project, any of a Toil project's tabs (Overview, Board, Dependencies,
550
627
  Pull requests, People, Worklog, Analyses), a saved analysis, a settings page, or a
551
628
  theme.
552
- - **Run** Sync now (where Toil UI keeps a cache), and on a dossier's page Ask (it
553
- focuses the Ask bar), Analyze, the agent that answers this chat, and Assign the
629
+ - **Run** Sync now (where Toil UI keeps a cache), **Use plain words** / **Use toil's own terms**, and on a Toil project's page Ask (it
630
+ focuses the Ask bar), Analyze, **Review a pull request**, **Ship: answer a review** and **Diagram <Toil project>** (each opens its job's page), **Open the Agents panel** (**Open the AI helpers panel** in plain words), the agent that answers this chat, and Assign the
554
631
  item you were on to an agent: the board card that had focus, or the item whose
555
632
  page is open.
556
633
  - Matching is fuzzy and ignores case: `pay12` finds `PAY-12`, and each word you
557
634
  type has to appear, in order. Results are grouped by kind, and the group with the
558
635
  best match comes first.
559
636
 
560
- ### Search across dossiers
637
+ ### Search across Toil projects
561
638
 
562
- With something typed, the palette searches the items of every dossier, by key and
563
- title. Each result shows its dossier and status and opens the item. It reads only
564
- what the last sync stored, never the tracker: opening it reads each dossier from
565
- the cache the way its dashboard does. A result from a dossier last synced more than
639
+ With something typed, the palette searches the items of every Toil project, by key and
640
+ title. Each result shows its Toil project and status and opens the item. It reads only
641
+ what the last sync stored, never the tracker: opening it reads each Toil project from
642
+ the cache the way its dashboard does. A result from a Toil project last synced more than
566
643
  a day ago, or whose last sync failed, says how old its copy is.
567
644
 
568
645
  ### Keyboard shortcuts
@@ -587,7 +664,7 @@ request: the kind, a title, the details and your email. It sends through
587
664
  first. Send works only while the box is ticked, and any edit clears it, so you
588
665
  agree to the report on screen and no other.
589
666
  - **Only what you typed.** toil adds its version and commit, nothing else: no
590
- dossier, connection, host or cached data.
667
+ Toil project, connection, host or cached data.
591
668
  - **The same lock as Settings.** `api/feedback` needs the session, the page's
592
669
  Origin and the CSRF token, takes the four fields and nothing else, and runs
593
670
  `toil feedback` and no other command. Your tick becomes the yes to the command's
@@ -599,7 +676,7 @@ request: the kind, a title, the details and your email. It sends through
599
676
 
600
677
  The dashboards read from a local cache, which a sync fills. Press **Sync now** in
601
678
  the Sync panel at the foot of the page. The sync makes the same toil calls the
602
- dashboards make, for every dossier, and stores the answers. The work items go
679
+ dashboards make, for every Toil project, and stores the answers. The work items go
603
680
  through toil's Open Work Item mapping, with their status changes and the pull
604
681
  requests, builds and deployments that name them.
605
682
 
@@ -609,36 +686,50 @@ requests, builds and deployments that name them.
609
686
  `updatedAt` moved. Only those items and their histories are fetched again.
610
687
  Pull requests, builds, deployments and iterations have no "changed since" in
611
688
  toil, so they're read again each time, bounded as the dashboards bound them.
689
+ Once a day, the Jira and Azure DevOps searches are also sent whole (ids only
690
+ where toil can), and an item they no longer list is dropped; if that listing
691
+ fails, the changes are kept and the next sync tries it again. Per-item calls
692
+ (histories, pull request gets) run 4 at a time across a Toil project.
693
+ Azure DevOps histories come from the project's revisions feed, read from the
694
+ watermark; an item is read on its own when the feed doesn't hold all of it.
612
695
  - **Every page.** Each call follows `meta.page.nextCursor` to the end, up to 200
613
696
  pages, and fails that source, saying so, rather than keep part of a listing.
614
- - **Each source on its own.** Each area a dossier reads (Jira, Bitbucket, Jenkins,
697
+ - **Each source on its own.** Each area a Toil project reads (Jira, Bitbucket, Jenkins,
615
698
  OpenShift and so on) is a source with its own state. A source that fails shows
616
699
  toil's message and fix in the Sync panel, and keeps its last good data, marked
617
- stale. The other sources and dossiers aren't touched. The next sync asks it
700
+ stale. The other sources and Toil projects aren't touched. The next sync asks it
618
701
  for everything since its last good sync, so nothing is missed.
619
702
  - **When.** The line under the header says when the data was synced. The panel
620
- says when each dossier was synced, and shows a running sync's progress
703
+ says when each Toil project was synced, and shows a running sync's progress
621
704
  (requests, pages and retries, from toil's own progress events).
622
705
  - **Where.** The cache is one SQLite file, `cache/toil-ui.db` in the data folder,
623
706
  through Node's built-in `node:sqlite`, so there's no native module. While Toil
624
707
  UI runs, its write-ahead log (`toil-ui.db-wal` and `toil-ui.db-shm`) sits beside
625
708
  it, and closing folds the log back into the file. It holds
626
709
  ticket content, so it stays on this machine and is readable by your account
627
- only. The analyses (#395) are kept in the same file, the newest 100 per dossier,
710
+ only. The analyses (#395) are kept in the same file, the newest 100 per Toil project,
628
711
  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
631
- it is older than the retention period, and with its dossier when toil no longer
712
+ - **For how long.** A Toil project's synced data (responses, items,
713
+ transitions, change refs, worklog facts and each source's state) expires together, once the
714
+ last sync that saved data for it is older than the retention period (30 days by default),
715
+ at start and after each sync. A sync that fails doesn't keep old data alive. Worklog facts that no
716
+ sync produces any more go about 1.25 times the retention period after they were last seen. The rest
717
+ goes when it is that old itself. The retention period
718
+ also sets how far back closed Jira and Azure DevOps items are read, with a
719
+ floor of 6 weeks (see What it reads). An analysis goes once
720
+ it is older than the retention period, and with its Toil project when toil no longer
632
721
  has it.
633
722
  - **Wiping it.** **Wipe the cache** in the Sync panel deletes it after asking
634
723
  first. `toil-ui wipe` does the same from a terminal, once `toil-ui` has
635
724
  stopped: a running Toil UI holds `toil-ui.lock` in the data folder, and the
636
725
  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.
726
+ - **Deleted tickets.** An item deleted in its tracker, or moved out of its
727
+ project, is dropped within a day by the whole listing a Jira or Azure DevOps
728
+ sync does once a day, since an incremental search only returns items that still
729
+ exist. So is an item closed longer ago than the read window. A GitHub issue
730
+ stays until the retention period ends or you wipe the cache.
640
731
 
641
- The page can run only the reads the dashboards make: `dossiers list` and `dossiers
732
+ The page can run only the reads the dashboards make: `projects list` and `Toil projects
642
733
  show`, and each area's search, history, pull request, build and deployment reads.
643
734
  Any other command is refused before it reaches toil, and a change to a tracker is
644
735
  never made from the page. The worklog's own calls are made by the server, never named
@@ -647,36 +738,61 @@ by the page: `toil audit list`, read-only, to see whether a proposal was applied
647
738
 
648
739
  ## The agent
649
740
 
650
- Every dossier page has an **Ask bar** in its top row: one line, with **Analyze**
651
- beside it. Pressing into it opens the **focused view**: the conversation takes the
652
- screen and the page steps back, with a slim strip that keeps the dossier, its sprint
741
+ Every Toil project page has an **Ask bar** in its top row: one line. Pressing into it opens the **focused view**: the conversation takes the
742
+ screen and the page steps back, with a slim strip that keeps the Toil project, its sprint
653
743
  and the agent answering in sight. **Escape** or **Close** puts it away; the
654
- conversation stays, for the rest of the dossier's pages, until you reload.
655
-
656
- - **Starter questions** are a row of chips before the first question, then a
657
- **Suggestions** menu.
744
+ conversation stays, for the rest of the Toil project's pages, until you reload.
745
+
746
+ - **The guided start** (#552) is what the chat shows before the first question:
747
+ "What would you like to know about {name}?", then nine plain questions in four groups
748
+ (How are we doing? What's in the way? Backlog. For others), beside **Before you ask**. What each is good for is its hover; the one line on the page is that "Who might need help?" never ranks anyone. The dialog's title is the project's name. You can still type your own, except with no AI helper set up, when the questions are off and the notice links to **Settings → AI helper**. Pressing a question asks its text
749
+ through the same path as typing it; after the first answer the same questions are the
750
+ **Suggestions** menu. The questions are `src/guided-questions.ts`, not the server's
751
+ starters, which still back `api/agent/starters`.
752
+ - **Before you ask** is on the page, never in a popover, as the same one line at every width,
753
+ "It reads what your connections can read, saved and live. It changes nothing.", with a
754
+ **What AI can see** button that opens the rest: what the AI can see (this Toil project's saved
755
+ copy, counted as items, code reviews, builds and deployments, and live reads through toil when
756
+ the copy is not enough, read-only) and what it can't do (change anything in the systems named,
757
+ see email or chat, read anything your connections can't already read). Who answers is the
758
+ header's to say, and what it costs is the usage line's.
759
+ - **How sure is this?** is under every finished answer, worked out by code
760
+ (`src/model/confidence.ts`) and never by the model, with an (i). **High**: every saved read worked, the data
761
+ is under 24 hours old, and at most 1 in 10 of the items the question needs a field of
762
+ lacks it. **Medium**: one of those slipped, or the answer names one item its tools never returned. **Low**: a read failed, the data is over 3 days
763
+ old, there are fewer than 3 items to go on (code reviews, for the question about reviews), or the answer names more than one item its tools never returned, or half of those it cites. A question from the guided start is checked against
764
+ the panels it needs; a typed question and Analyze against every read. Under the word and its reason is one folded line, "What it looked at · 3 s · about $0.04 of usage (estimate)", which opens to the items the answer cited as links (a cited id the project doesn't hold as the bare
765
+ id) and the usage breakdown. "Suggestions only. Nothing was changed." is said under the first answer of a conversation, not every one; "Answered by" appears under an answer only when it differs from the header's. The answer's own heading is not drawn (it repeats the question), though a screen reader still has it. The existing proposal
766
+ cards still show the command to run, with no approve button.
658
767
  - **Answers stream in** as the agent writes them, under a **status line** that says
659
768
  what it is doing: reading the cache with `owi_query`, reading live through toil with
660
769
  `github issue list`, writing, and at the end how long it took. **Stop** cancels the
661
770
  question on the server and keeps what had arrived. Claude and Copilot stream as they
662
771
  write; Codex's SDK hands over its text a message at a time, so with Codex the status
663
772
  line is what moves between messages.
664
- - **The wording follows the theme**: the bar's placeholder, the welcome and the status
665
- words are in each game theme's voice, and Plain stays neutral. The starter questions
773
+ - **The wording follows the theme** when themed wording is on and plain words are off: the bar's placeholder, the welcome and the status
774
+ words are in each game theme's voice, and Plain stays neutral. With plain words on (the default), they read in plain words. The starter questions
666
775
  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.
676
- - **Citations are chips**: in every answer, each `[[id]]` is a chip with the item's
677
- key, title and status, linking to its page (a pull request to its host). Hovering or
678
- focusing one shows its type, assignee, estimate, sprint and last update. An id the
679
- dossier doesn't hold stays the bare id, marked, and the server's check above the
776
+ - **Analyze** briefs the Toil project in one press (#494). It is the guided start's first
777
+ question, "Give me the full briefing", and still the command palette's Get a briefing and the
778
+ Analyses tab's button; the Ask bar has no button of its own for it. Its question comes from toil,
779
+ `toil projects analyze prompt <toilProject> --host toil-ui`: the standard method with
780
+ the Toil project's own lenses and focus (Tuning Analyze, above). It answers with a
781
+ briefing block, which the server lifts out of the answer and checks, every id in it
782
+ against what the agent's tools read: a recommendation, then the reasons, each item
783
+ with why it's there and the next step, then what changed, and anything the
784
+ Toil project's focus left out. The briefing, the item drawer, the chat and the analysis
785
+ page all lay it out, with the rest of the answer as **Evidence**, folded until you
786
+ open it. An answer with no briefing block is shown as it came, and says so. With a
787
+ toil that has no `projects analyze prompt`, Analyze asks Toil UI's own question
788
+ instead, and the answer warns that it did. Each whole Analyze is kept in the
789
+ Toil project's **Analyses** tab, and the answer links to it.
790
+ - **Citations are links in the text**: in every answer, each `[[id]]` is an ordinary link
791
+ (a short source name such as ADO or GH, the item's key and a cut title) to its page (a
792
+ pull request to its host). Hovering or focusing one shows the whole title, its source and
793
+ status, type, assignee, estimate, sprint and last update; the status is also in the
794
+ link's name for a screen reader. An id the
795
+ Toil project doesn't hold stays the bare id, marked, and the server's check above the
680
796
  answer still names any id its tools never returned.
681
797
  - **Each question carries the chat so far**: its last 8 questions and answers, each
682
798
  answer cut to 1,500 characters. An item an earlier answer named is still checked
@@ -686,6 +802,18 @@ conversation stays, for the rest of the dossier's pages, until you reload.
686
802
  from its next question, which carries the conversation so far; the default stays in
687
803
  Settings. An adapter that can't answer is listed with the reason and **Install** or
688
804
  **Fix**, never left out. Each answer names the adapter and model that wrote it.
805
+ - **The chat remembers its agent for each Toil project** (#494). A whole answer, Analyze or an
806
+ ordinary question, records the agent it was asked of, in `<data folder>/toil-project-agents.json` (an adapter name per
807
+ Toil project name, Toil UI's own state, never in the Toil project file). The next time the chat
808
+ opens on that Toil project it starts on that agent if it can still answer, else on the
809
+ default from Settings, Agent (Claude, GitHub Copilot or Codex), else the first agent
810
+ that is ready, else as before, with the server trying the default and saying why it
811
+ can't. A few words beside **Answered by** say which: "last used on this Toil project",
812
+ "your default", "your default can't run", "the first one ready" or
813
+ "picked for this chat". Picking another agent and asking updates the memory; a question that names no
814
+ agent, or an answer that fails, is stopped or comes back empty, doesn't. Renaming a Toil project moves its
815
+ memory, and a Toil project toil no longer has is forgotten on the next full sync. The sample
816
+ remembers nothing.
689
817
 
690
818
  The chat answers with the agent your organization already approved, on the
691
819
  subscription you already have. Toil UI has three adapters, each an optional peer
@@ -704,9 +832,12 @@ toil's config, and has no field for a key: each SDK signs in the way its CLI doe
704
832
 
705
833
  ### Installing an adapter's SDK
706
834
 
707
- **Settings, Agent** lists each adapter: whether its SDK is installed and at which
708
- version against the one Toil UI was tested with, which CLI it would start, and
709
- anything worth knowing. A missing SDK has an **Install** button, which shows the one
835
+ **Settings, Agent** (**AI helper** in plain words) opens on the steps to get going and each
836
+ helper with its state (Ready, Not set up yet in a calm tone, or Needs one more step with the
837
+ reason shown), and an **Install** button on each helper that isn't installed. Whether its SDK
838
+ is installed and at which version against the one Toil UI was tested with, which CLI it would
839
+ start, and anything worth knowing, are one step in under **Details for whoever sets it up**;
840
+ models, the CLI path and the endpoint are behind **Advanced**. A missing SDK has an **Install** button, which shows the one
710
841
  command it will run, word for word, before anything runs:
711
842
 
712
843
  ```bash
@@ -754,12 +885,12 @@ for (docs/decisions/343-ask-up-front.md).
754
885
  `TOIL_*` variables, `GITHUB_TOKEN` and CI tokens never reach it. Not found is a plain
755
886
  error naming the CLI and the fix. On Windows a `.cmd` shim can't be started by the
756
887
  SDKs, so point at the `.exe` (Copilot's npm shim is the exception, above).
757
- - **Read-only tools, one dossier.** The agent gets `owi_query`, `owi_get`,
888
+ - **Read-only tools, one Toil project.** The agent gets `owi_query`, `owi_get`,
758
889
  `owi_similar` (likely duplicates, scored as `toil util owi similar` scores them)
759
890
  and `owi_history` over the cache, `pr_query`, `pr_get` and `pr_metrics` over its
760
891
  pull requests (what each waits on, its flags, and flow figures by author kind with
761
892
  their sample sizes), `people_list` and `person_get` (each person's plate as the
762
- People view works it out, with the dossier read live through `dossiers show`, and
893
+ People view works it out, with the Toil project read live through `projects show`, and
763
894
  told it describes load, never performance), `readiness_list` and
764
895
  `readiness_get` (each item's readiness verdict and its rows, as the Command Center
765
896
  works them out), `proposal_fields` (a write command's input fields,
@@ -767,7 +898,7 @@ for (docs/decisions/343-ask-up-front.md).
767
898
  with what it can't vouch for), `standup_report` (a range of days as the Stand-up folds
768
899
  them, each line numbered), `proposal_fields` (a write command's input fields,
769
900
  from toil's registry), and `toil mcp`'s read tools for live lookups, called through
770
- toil's `execute()` with `readOnly: true`. The dossier is fixed to the one on screen.
901
+ toil's `execute()` with `readOnly: true`. The Toil project is fixed to the one on screen.
771
902
  There is no write tool, and each SDK's own tools (shell, files, web, plugins, other
772
903
  MCP servers) are switched off.
773
904
  - **Citations are checked.** Every answer cites the work items and pull requests it
@@ -801,18 +932,23 @@ for (docs/decisions/343-ask-up-front.md).
801
932
  proposals or what the tools can do. **Show the full prompt** shows exactly what
802
933
  the agent is sent.
803
934
 
804
- With no adapter chosen, the chat says so and names the three; its switcher can still
805
- choose an installed one for that chat. `toil-ui --sample` keeps the scripted agent,
806
- which answers its starter questions and Analyze from the sample data.
935
+ With no adapter chosen, the chat says in plain words that no AI helper is set up and where
936
+ an engineer sets one up (Settings, Agent), with the three adapters and their packages one
937
+ step in, behind **Details for whoever sets it up**; its switcher can still
938
+ choose an installed one for that chat. The notice goes as soon as a helper can answer: the chat
939
+ reads the helpers again whenever the page moves, so installing on the Settings page needs no
940
+ reload. A helper that is installed but can't start yet says so instead, with the reason one step
941
+ in. `toil-ui --sample` keeps the scripted agent,
942
+ which answers its starter questions, Analyze and the workflow jobs from the sample data (a job's answer says nothing was read and lists every check as unchecked).
807
943
 
808
944
  ### Not ticketed yet
809
945
 
810
946
  When you ask the chat for work that names no ticket (not a question, which ends in `?` or
811
947
  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
812
- dossier's open items likeliest to cover it, scored as `toil util owi similar` scores
948
+ Toil project's open items likeliest to cover it, scored as `toil util owi similar` scores
813
949
  them, each with why. Attach the work to one by naming its key in your branch and
814
950
  commits, which writes nothing, or press **Ticket this** for proposals: a sub-task
815
- under each match, and a new ticket on the dossier's tracker. They are proposal cards
951
+ under each match, and a new ticket on the Toil project's tracker. They are proposal cards
816
952
  like the chat's others, with the command line to run through toil's write gate, and
817
953
  nothing is created until you run one. With no match, it says there is no likely
818
954
  ticket and offers only a new one. It asks once per chat, and **Not now** hides it.
@@ -829,20 +965,20 @@ called):
829
965
  | 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 |
830
966
  | 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 |
831
967
 
832
- - **Under each answer**, one line per model: `2.1k in · 380 out · 14k cached · cache
968
+ - **Under each answer**, one line in its folded line, "about $0.04 of usage (estimate)", or "(not billed on your plan)" on a Claude plan. The fold opens to one line per model: `2.1k in · 380 out · 14k cached · cache
833
969
  write not reported · ~$0.012 (SDK estimate)`. A figure the SDK didn't report reads
834
- "not reported", never 0.
835
- - **In the chat's heading**, the chat's running total, split by model, and how full
970
+ "not reported", never 0. A cap notice stays in the open.
971
+ - **In the chat's footer**, from the second answer (one answer's usage is the chat's), the chat's running total, split by model, and how full
836
972
  the last answer's context got, where the SDK says (Claude and Copilot; Codex's SDK
837
- doesn't).
973
+ doesn't). On a phone the chat's header is one line, "Answered by … · Change".
838
974
  - **Settings, Agent usage** (beside Usage, which counts toil's own commands): the last
839
- 30 days by day, adapter, model and dossier, the chats that used the most, and an
975
+ 30 days by day, adapter, model and Toil project, the chats that used the most, and an
840
976
  **Export as CSV** download made in the page.
841
977
  - **One adding-up rule**, `addUp` in `src/model-usage.ts`, read by the server's caps,
842
978
  the footer, the heading and Settings: reports with one id are one report, merged to
843
979
  the highest of each figure (a running total), and different ids are summed.
844
980
  - **The ledger** is the cache's `usage` table, apart from everything a sync writes: a
845
- sync's cleanup or a dossier leaving never lowers a total. It follows the cache's
981
+ sync's cleanup or a Toil project leaving never lowers a total. It follows the cache's
846
982
  retention, `toil-ui wipe` clears it, and it is never sent anywhere.
847
983
 
848
984
  **Caps** are optional and off until you turn one on, under Settings, Agent usage: a
@@ -868,29 +1004,29 @@ you apply it.
868
1004
  |---|---|---|
869
1005
  | **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 |
870
1006
  | **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 |
871
- | **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 |
1007
+ | **Implement** | Works in a copy of the Toil project 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 |
872
1008
 
873
1009
  - **Refine and investigate** get the same read-only tools as the chat (`owi_*`, `pr_*`,
874
1010
  `proposal_fields` and toil's live reads), with no shell and no file writes.
875
1011
  - **Implement runs on Codex only, for now.** Codex's own sandbox, `workspace-write`,
876
1012
  holds the agent's commands and writes to the clone, with no network and none of the
877
1013
  temp folders Codex adds by default, on Windows (its `unelevated` restricted-token sandbox), macOS and Linux. The clone is
878
- `<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
879
- repository needs a local path (`toil dossiers add-repo <dossier> <folder>`). The agent stages its change and never commits, pushes or fetches; the
1014
+ `<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 Toil project's
1015
+ repository needs a local path (`toil projects add-repo <toilProject> <folder>`). The agent stages its change and never commits, pushes or fetches; the
880
1016
  staged diff is shown through toil's own `git status` and `git diff`, and the commit
881
1017
  and push are a proposal of the exact git lines to run, since toil has no command
882
1018
  that pushes.
883
1019
  - **States**: `queued` (waiting for a free slot, or for a person to press Start),
884
1020
  `working`, `needs you` (proposals or questions to review, or an item the agent
885
1021
  thought was trying to instruct it), `done` and `failed`. The **Agents** sidebar beside
886
- every dossier tab shows each assignment's state, mode, adapter, run time and what it
1022
+ every Toil project tab shows each assignment's state, mode, adapter, run time and what it
887
1023
  used, and the People view shows each agent's assignments.
888
1024
  - **From the Command Center**, "Start every ready item" assigns each slated item in
889
1025
  implement mode, in order, on Codex (or the adapter chosen in Settings, when it can
890
- implement), in the dossier's one repository with a local path, and says what it
1026
+ implement), in the Toil project's one repository with a local path, and says what it
891
1027
  queued or why it started nothing.
892
1028
  - **The tracker only queues.** An item labelled `agent:refine`, `agent:investigate` or
893
- `agent:implement`, or assigned to one of the dossier's agents (its `people` with
1029
+ `agent:implement`, or assigned to one of the Toil project's agents (its `people` with
894
1030
  `kind: agent`, which queues a refine), appears in the **Agent inbox** on the next
895
1031
  read. It runs only when a person presses Start.
896
1032
  - **Applying a proposal** runs its toil command, the one the server stored when the
@@ -907,7 +1043,7 @@ you apply it.
907
1043
  - **The transcript** keeps the prompts, every tool call, the agent's text, the
908
1044
  commands and file changes Codex reports, and each proposal and what came of it.
909
1045
  Each assignment also records what it started on: the toil and Toil UI versions, the
910
- adapter and model, the tools, and SHA-256 fingerprints of the dossier, the item and
1046
+ adapter and model, the tools, and SHA-256 fingerprints of the Toil project, the item and
911
1047
  the prompt, and the install fingerprint a later look holds it to (Stale sessions, below). Assignments are kept under the cache, in
912
1048
  `<data folder>/cache/assignments/`, so a wipe deletes them.
913
1049
  - **For programs on the same server**, `api/assignments` lists, assigns, starts,
@@ -917,7 +1053,7 @@ you apply it.
917
1053
  ## Stale sessions
918
1054
 
919
1055
  An agent works from the instructions it got when it started. Upgrade toil, edit the
920
- dossier or change your instructions under **Settings, Agent**, and the chats and
1056
+ Toil project or change your instructions under **Settings, Agent**, and the chats and
921
1057
  assignments already going are still on the old ones. Toil UI records what each one
922
1058
  started on, says which have gone stale and why, and renews them on request.
923
1059
 
@@ -925,7 +1061,7 @@ started on, says which have gone stale and why, and renews them on request.
925
1061
  run starts, keeps an install fingerprint: toil's and Toil UI's version and commit,
926
1062
  one SHA-256 per toil area of the tools the agent was handed (Toil UI loads no skill
927
1063
  page, so those tools are the toil instructions its agent reads), SHA-256 of the
928
- dossier as `toil dossiers show` reads it, and SHA-256 of the prompts (the system
1064
+ Toil project as `toil projects show` reads it, and SHA-256 of the prompts (the system
929
1065
  prompt, the starters or the mode's task, and your own instructions and voice). The
930
1066
  theme on screen isn't part of it. An assignment recorded before this has none, and
931
1067
  is never called stale.
@@ -933,7 +1069,7 @@ started on, says which have gone stale and why, and renews them on request.
933
1069
  assignment page compares what the session started on with the current fingerprint,
934
1070
  whose builds are the ones on disk, read again only when their files change. The
935
1071
  reason names what moved: "started on toil 0.1.0-alpha.3 · now alpha.4 · skills
936
- changed: github · dossier changed". A session's earlier turns aren't marked; only
1072
+ changed: github · Toil project changed". A session's earlier turns aren't marked; only
937
1073
  the instructions it started on are.
938
1074
  - **Where it shows.** A **Stale** badge with the reason on the chat (in the Ask bar and
939
1075
  the focused view), on each assignment in the Agents sidebar and on its page, and on the
@@ -946,7 +1082,7 @@ started on, says which have gone stale and why, and renews them on request.
946
1082
  stays readable, marked as renewed. Renew never interrupts a turn: a chat that is
947
1083
  answering and a working assignment wait, and an assignment that needs you is
948
1084
  skipped until you've reviewed it.
949
- - **Renew all stale**, in the Agents sidebar, lists every stale session of the dossier
1085
+ - **Renew all stale**, in the Agents sidebar, lists every stale session of the Toil project
950
1086
  first, the chat included, each saying whether it renews or why it's skipped, and
951
1087
  renews the rest with one press.
952
1088
  - **The server itself.** When toil or Toil UI on disk is newer than the running
@@ -980,15 +1116,15 @@ call, its progress, or a state that didn't change never notifies.
980
1116
  the views.
981
1117
  - **Where it listens.** The server's `api/assignments/events?since=latest` stream,
982
1118
  which carries what a notice says with each event, and a minute's read of the
983
- dossier on screen for sessions gone stale.
1119
+ Toil project on screen for sessions gone stale.
984
1120
 
985
1121
  ### Notification history
986
1122
 
987
1123
  The **bell** in the header (beside **Menu** on a narrow screen) counts the unread and
988
1124
  opens the last 50 things worth telling you, newest first: each change a notice carried
989
1125
  (needs you, done, failed, stopped at a usage cap, gone stale), each sync's result, from
990
- the Sync panel, with the dossier that failed, and when each happened. Every entry links
991
- to what it's about: the assignment, the dossier, or the Dossiers view. **Mark all read**
1126
+ the Sync panel, with the Toil project that failed, and when each happened. Every entry links
1127
+ to what it's about: the assignment, the Toil project, or the Toil projects view. **Mark all read**
992
1128
  clears the count and keeps the entries. The bell keeps a change that quiet hours held
993
1129
  back, and one whose notice you dismissed; which changes reach it is the notification
994
1130
  settings' choice. It's kept in this browser's `localStorage`, shared by its tabs (with one
@@ -1000,7 +1136,7 @@ the worklog's facts, never from the bell.
1000
1136
  Eight built-in themes: Plain, Crate (the default), Harvest, Starship, Realm, Sprawl,
1001
1137
  Frontier and Overworld. Pick
1002
1138
  one from the header, or under **Settings, General**, where two checkboxes say how far
1003
- it goes, both on by default:
1139
+ it goes, both off by default (#552):
1004
1140
 
1005
1141
  - **Themed wording:** the theme's own lede, eyebrows, dashboard notes, empty
1006
1142
  states and loading lines, and its names for a sprint, a board or an epic beside
@@ -1011,6 +1147,9 @@ it goes, both on by default:
1011
1147
  dungeon master in Realm, a laconic netrunner in Sprawl, a dry telegraph operator
1012
1148
  in Frontier, an old sage in a cave in Overworld. It changes phrasing only.
1013
1149
 
1150
+ Every theme has a light and a dark scheme. **Appearance**, in Settings, General or the
1151
+ command palette, picks one; System, the default, follows your operating system.
1152
+
1014
1153
  A theme with particles also gets **Particles and ambient effects**, kept for each
1015
1154
  theme on its own: off, that theme's particles are gone entirely, while its other
1016
1155
  motion keeps following **Reduce motion and effects** (and the operating system's
@@ -1018,7 +1157,7 @@ reduced-motion setting, which stops everything).
1018
1157
 
1019
1158
  Crate, Harvest, Starship, Realm, Sprawl, Frontier and Overworld also have **theme moments**: a launch splash while the first read
1020
1159
  runs, their own loading screens with the real progress and a rotating line of their own,
1021
- an entrance as a dossier opens, a transition between its tabs, and a short moment when a
1160
+ an entrance as a Toil project opens, a transition between its tabs, and a short moment when a
1022
1161
  sync brings an item done, a build passed or failed, a blocker cleared, a pull request
1023
1162
  merged, or a sprint's end. **Theme motion**, under Settings, General, plays them in full,
1024
1163
  subtly or not at all, and is off whenever reduced motion is asked for. Every loading
@@ -1042,8 +1181,8 @@ Any program on the machine, or a web page using DNS rebinding, can reach a local
1042
1181
  port, so the server lets in only the browser holding this launch's token:
1043
1182
 
1044
1183
  - **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
1184
+ for a session id, which the tab keeps in `sessionStorage` (see Start it) and
1185
+ sends as a header on every API call. Nothing is kept in a cookie: a browser would send one to any other server
1047
1186
  on `127.0.0.1`, whatever its port.
1048
1187
  - **The Host header.** Only the exact `127.0.0.1:<port>` it printed is answered.
1049
1188
  - **No CORS.** No `Access-Control-*` header is ever sent. Every POST also needs the
@@ -1071,22 +1210,22 @@ GitHub CLI signed in (`gh auth login`), or `TOIL_GITHUB_TOKEN` set in the shell.
1071
1210
  - **The token** comes from `gh auth token` each time it starts and goes only into
1072
1211
  Toil UI's environment, as `TOIL_GITHUB_TOKEN`. It's never written to a file or
1073
1212
  printed. `GITHUB_TOKEN` and other `TOIL_*` variables in your shell are left out.
1074
- - **The dossiers**, made with `toil dossiers init` and `link` and checked with
1075
- `toil dossiers check`: one for `--repo`, and `toil-self` for the public
1213
+ - **The Toil projects**, made with `toil projects init` and `link` and checked with
1214
+ `toil projects check`: one for `--repo`, and `toil-self` for the public
1076
1215
  `imagile-dev/toil` unless `--no-self`. `--repo` defaults to
1077
1216
  `imagile-dev/toil-sandbox` (as `sandbox`), which is private to Imagile's
1078
1217
  maintainers; anyone else passes their own repository, or seeds a sandbox of their
1079
1218
  own (below).
1080
1219
  - **toil from this checkout.** Each start builds toil from the clone into
1081
1220
  `.scratch/toil` (`npm run build` with `TOIL_BUILD_DIR`, a few seconds), and both the
1082
- dossier setup and Toil UI run on that build, not on the published toil
1221
+ Toil project setup and Toil UI run on that build, not on the published toil
1083
1222
  `ui/package.json` pins. Toil UI is started with `node --import
1084
1223
  ui/scripts/local-toil-hook.mjs`, which resolves `@imagile-dev/toil/api` to
1085
1224
  `.scratch/toil/api.js` and says so on stderr. So a command `ui/` calls before its
1086
1225
  release works here. The committed `dist/` and `node_modules` are left alone, and a
1087
1226
  plain `node ui/dist/server/toil-ui.js` still runs on the pinned toil.
1088
1227
  - **Then** it starts `ui/dist/server/toil-ui.js` on loopback and prints its URL.
1089
- Press **Sync now**, then open a dossier. `--port <n>` fixes the port, and
1228
+ Press **Sync now**, then open a Toil project. `--port <n>` fixes the port, and
1090
1229
  `--home <dir>` uses another folder.
1091
1230
  - **Ask with Codex.** Install the SDK in the clone without saving it
1092
1231
  (`npm install --no-save --ignore-scripts @openai/codex-sdk@0.160.0`), then choose
@@ -1114,6 +1253,12 @@ GitHub CLI signed in (`gh auth login`), or `TOIL_GITHUB_TOKEN` set in the shell.
1114
1253
  script says so: run `claude` once in a terminal, which refreshes its own sign-in,
1115
1254
  or set a token from `claude setup-token`, and start the script again.
1116
1255
 
1256
+ To run the same build against your own `~/.toil` instead (your connections and
1257
+ Toil projects as they are, changed only by what you save in Settings, with Toil UI's own
1258
+ data in `.scratch/toil-ui`), run `node ui/scripts/dev-mine.mjs`.
1259
+ That's the way to try unreleased changes on real work (`skills/toil/install.md`,
1260
+ Trying unreleased changes).
1261
+
1117
1262
  ## Verify before you open a PR: `npm run verify:ui`
1118
1263
 
1119
1264
  One command checks Toil UI the way a reviewer would, and writes what it found to
@@ -1136,27 +1281,28 @@ npm run verify:ui -- --no-build --starter standup
1136
1281
  is what the published package runs on.
1137
1282
  - **Sample data:** `toil-ui --sample` in a throwaway home, every view through the
1138
1283
  layout check (`scripts/layout-check.mjs`) in every theme and scheme at 375, 768 and
1139
- 1440px. On each dossier's dashboard it also drags a board card to the next column
1284
+ 1440px. On each Toil project's dashboard it also drags a board card to the next column
1140
1285
  with real input, a mouse and at 375px a finger, and fails when the card doesn't
1141
1286
  follow the pointer or the dropped move doesn't show in the target column. It needs
1142
1287
  only a browser, so it runs anywhere, CI included.
1143
- - **First run:** `toil-ui` on an empty home, with no connections, no dossiers and no
1144
- `TOIL_*` variable from your shell, through the same check: its Dossiers view must
1288
+ - **First run:** `toil-ui` on an empty home, with no connections, no Toil projects and no
1289
+ `TOIL_*` variable from your shell, through the same check: its Toil projects view must
1145
1290
  show the three-step checklist, and the palette and the shortcuts sheet open over it.
1146
1291
  - **Real data:** the home `dev-real.mjs` sets up, made fresh at
1147
1292
  `.scratch/verify/home`, on `imagile-dev/toil-sandbox` with the token from `gh auth
1148
- token` in Toil UI's environment only. It syncs the `sandbox` dossier and runs the
1149
- same check over the home page, the dossier and its Board and Dependencies tabs, its worklog and stand-up, one of its items and the settings pages,
1150
- except that its header may fold into the Menu at 1440px, since a real dossier's name
1151
- and links can genuinely fill the row.
1293
+ token` in Toil UI's environment only. It syncs the `sandbox` Toil project and runs the
1294
+ same check over the home page, the Toil project and its Board and Dependencies tabs, its worklog and stand-up, one of its items and the settings pages,
1295
+ except that its header may fold into the Menu at 1440px, since a real Toil project's name
1296
+ and links can genuinely fill the row, and its Usage page's failed-command lines are
1297
+ opened on the sample only, since real data may have none.
1152
1298
  Without a GitHub sign-in it skips this part and says so; nothing else depends on it.
1153
1299
  - **`--ask`** asks Codex one starter question (`hygiene` unless `--starter <id>`) and
1154
1300
  checks that an answer arrived, that the server verified every `[[id]]` it cites,
1155
1301
  that its proposals parsed, that nothing ran (no write in toil's audit log for the
1156
1302
  run), and that `codex mcp list` in Toil UI's Codex home shows only `toil_ui`. Then it
1157
1303
  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
1304
+ (#395): that Analyze was kept with its briefing (a recommendation, and its first
1305
+ three reasons as the history's issues); then it changes the Toil project's WIP limit in the scratch home (`toil projects
1160
1306
  wip-limit --replace`), asks Analyze again, checks the history lists both, newest
1161
1307
  first, the second compared with the first, and puts the Overview, the Analyses tab
1162
1308
  and the second analysis opened through the layout check, shot. It needs the Codex CLI signed in and the
@@ -1171,9 +1317,9 @@ npm run verify:ui -- --no-build --starter standup
1171
1317
  - **It stops** every server and browser it started, and exits 1 on any problem.
1172
1318
 
1173
1319
  `--source ado` runs the real-data part against an Azure DevOps Services board
1174
- 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
1320
+ instead (the `ado-board` Toil project, as `dev-real.mjs --source ado` makes it below),
1321
+ with `TOIL_ADO_BASE_URL`, `TOIL_ADO_PAT` and `--project <name>` (else
1322
+ `TOIL_ADO_PROJECT`); without them it skips that part and says why. Each source is
1177
1323
  one entry in `SOURCES` in `scripts/verify.mjs`. Set `CHROME_PATH` if the browser it finds doesn't draw headless; Playwright's
1178
1324
  Chromium works where an installed Chrome doesn't.
1179
1325
 
@@ -1204,19 +1350,19 @@ toil's `github` area doesn't read.
1204
1350
  ### An Azure DevOps Services board
1205
1351
 
1206
1352
  `--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`:
1353
+ toil's `ado` area on a Services connection, with a Toil project named `ado-board`:
1208
1354
 
1209
1355
  ```bash
1210
1356
  node ui/scripts/dev-real.mjs --source ado --project "<project>"
1211
1357
  ```
1212
1358
 
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`
1359
+ It needs `TOIL_ADO_BASE_URL` (`https://dev.azure.com/<organization>`) and
1360
+ `TOIL_ADO_PAT` (an organization-scoped token with Work Items, Read) in the
1361
+ shell. They go into Toil UI's environment only: toil makes its `ado` (deployment cloud)
1216
1362
  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
1218
- 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.
1363
+ written to the config file. `--project`, or `TOIL_ADO_PROJECT`, names the
1364
+ project; the Toil project in the scratch home holds it. The Toil project names no repository,
1365
+ so no pull requests are read; add `repo` to its `ado` section for them.
1220
1366
 
1221
1367
  To fill a board with made-up work, `ui/scripts/ado-seed/` seeds one from Open Work
1222
1368
  Items. `items.owi.json` holds 45 of them across the three sample products
@@ -1249,9 +1395,9 @@ To check what toil reads back, map the board's output and compare it with the fi
1249
1395
  difference, leaving out what the server assigns.
1250
1396
 
1251
1397
  ```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
1398
+ toil ado work-item iterations --project "<project>" > board.jsonl
1399
+ toil ado work-item get-many <ids…> >> board.jsonl
1400
+ toil ado work-item history <id> >> board.jsonl # once for each id
1255
1401
  toil util owi map board.jsonl > mapped.json
1256
1402
  node ui/scripts/ado-seed/compare.mjs mapped.json --project "<project>" --backdated
1257
1403
  ```
@@ -1288,7 +1434,7 @@ npm run screens:sheet -w ui -- --theme realm --width 768 --motion full
1288
1434
  `ui/.moments/sheets/<theme>-<width>-<motion>.png`, ready to attach to the PR, with its
1289
1435
  frames and an HTML copy in a folder beside it. A sheet shows the splash arriving, held and
1290
1436
  handing over; the loading screen as its loops turn; each event moment the theme declares
1291
- coming in, held and going out, cropped to the card; the dossier entrance; and a change of
1437
+ coming in, held and going out, cropped to the card; the Toil project entrance; and a change of
1292
1438
  tab. Every frame is a still: the engine's animations are caught paused as they start and
1293
1439
  stepped by hand, so a sheet is the same on every run. `--width` and `--motion` repeat, and
1294
1440
  replace the defaults.
@@ -1308,7 +1454,7 @@ its table. For the same reason neither command runs in CI, and neither is part o
1308
1454
  | Port | `--port` | `TOIL_UI_PORT` | `0`: the OS picks a free one |
1309
1455
  | Base path | `--base-path` | `TOIL_UI_BASE_PATH` | `/` |
1310
1456
  | Data folder | `--data-dir` | `TOIL_UI_DATA_DIR` | `~/.toil-ui` |
1311
- | Retention | `--retention-days` | `TOIL_UI_RETENTION_DAYS` | `30` (1 to 3650) |
1457
+ | 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
1458
 
1313
1459
  A flag beats its env var. Any bind address other than loopback is refused in this
1314
1460
  release. The data folder is Toil UI's own, apart from toil's `~/.toil/`, and holds