@nanocollective/roster 0.1.0-alpha.9 → 0.1.0-beta.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (145) hide show
  1. package/README.md +5 -0
  2. package/dist/cli.js +4067 -1950
  3. package/dist/worker/assets/assets/css/base.css +312 -0
  4. package/dist/worker/assets/assets/css/brain.css +116 -0
  5. package/dist/worker/assets/assets/css/diff.css +33 -0
  6. package/dist/worker/assets/assets/css/graph.css +39 -0
  7. package/dist/worker/assets/assets/css/health.css +75 -0
  8. package/dist/worker/assets/assets/css/home.css +101 -0
  9. package/dist/worker/assets/assets/css/inbox.css +199 -0
  10. package/dist/worker/assets/assets/css/layout.css +175 -0
  11. package/dist/worker/assets/assets/css/markdown.css +96 -0
  12. package/dist/worker/assets/assets/css/runs.css +13 -0
  13. package/dist/worker/assets/assets/css/search.css +48 -0
  14. package/dist/worker/assets/assets/css/setup.css +194 -0
  15. package/dist/worker/assets/assets/js/api.js +161 -0
  16. package/dist/worker/assets/assets/js/app.js +465 -0
  17. package/dist/worker/assets/assets/js/dialog.js +196 -0
  18. package/dist/worker/assets/assets/js/dom.js +131 -0
  19. package/dist/worker/assets/assets/js/homesort.js +174 -0
  20. package/dist/worker/assets/assets/js/icons.js +142 -0
  21. package/dist/worker/assets/assets/js/inflight.js +18 -0
  22. package/dist/worker/assets/assets/js/lightbox.js +273 -0
  23. package/dist/worker/assets/assets/js/md.js +406 -0
  24. package/dist/worker/assets/assets/js/mdedit.js +84 -0
  25. package/dist/worker/assets/assets/js/mention.js +264 -0
  26. package/dist/worker/assets/assets/js/readiness.js +70 -0
  27. package/dist/worker/assets/assets/js/refresh.js +197 -0
  28. package/dist/worker/assets/assets/js/router.js +20 -0
  29. package/dist/worker/assets/assets/js/search.js +366 -0
  30. package/dist/worker/assets/assets/js/state.js +213 -0
  31. package/dist/worker/assets/assets/js/textdiff.js +96 -0
  32. package/dist/worker/assets/assets/js/views/app.js +145 -0
  33. package/dist/worker/assets/assets/js/views/brain.js +260 -0
  34. package/dist/worker/assets/assets/js/views/changed.js +157 -0
  35. package/dist/worker/assets/assets/js/views/checklist.js +115 -0
  36. package/dist/worker/assets/assets/js/views/credential.js +84 -0
  37. package/dist/worker/assets/assets/js/views/docs.js +174 -0
  38. package/dist/worker/assets/assets/js/views/files.js +139 -0
  39. package/dist/worker/assets/assets/js/views/graph.js +436 -0
  40. package/dist/worker/assets/assets/js/views/health.js +304 -0
  41. package/dist/worker/assets/assets/js/views/hire.js +593 -0
  42. package/dist/worker/assets/assets/js/views/home.js +585 -0
  43. package/dist/worker/assets/assets/js/views/inbox.js +1558 -0
  44. package/dist/worker/assets/assets/js/views/memory.js +150 -0
  45. package/dist/worker/assets/assets/js/views/org.js +195 -0
  46. package/dist/worker/assets/assets/js/views/orgedit.js +240 -0
  47. package/dist/worker/assets/assets/js/views/paste.js +216 -0
  48. package/dist/worker/assets/assets/js/views/prompt.js +457 -0
  49. package/dist/worker/assets/assets/js/views/repos.js +97 -0
  50. package/dist/worker/assets/assets/js/views/runonce.js +94 -0
  51. package/dist/worker/assets/assets/js/views/runs.js +182 -0
  52. package/dist/worker/assets/assets/js/views/setup.js +557 -0
  53. package/dist/worker/assets/assets/js/views/staff.js +291 -0
  54. package/dist/worker/assets/assets/js/views/todo.js +62 -0
  55. package/dist/worker/assets/assets/js/yaml.js +134 -0
  56. package/dist/worker/assets/docs-images/brain.jpg +0 -0
  57. package/dist/worker/assets/docs-images/home.jpg +0 -0
  58. package/dist/worker/assets/docs-images/org.jpg +0 -0
  59. package/dist/worker/assets/docs-images/prompt.jpg +0 -0
  60. package/dist/worker/assets/docs-images/setup-org.jpg +0 -0
  61. package/dist/worker/assets/docs-images/setup-plan.jpg +0 -0
  62. package/dist/worker/assets/docs-images/staff.jpg +0 -0
  63. package/dist/worker/assets/index.html +82 -0
  64. package/dist/worker/index.js +4430 -0
  65. package/docs/README.md +2 -2
  66. package/docs/architecture.md +1 -1
  67. package/docs/charters/analyst.md +65 -0
  68. package/docs/charters/community.md +63 -0
  69. package/docs/charters/designer.md +65 -0
  70. package/docs/charters/devops.md +65 -0
  71. package/docs/charters/pm.md +70 -0
  72. package/docs/charters/qa.md +65 -0
  73. package/docs/charters/writer.md +63 -0
  74. package/docs/commands.md +9 -3
  75. package/docs/concepts.md +33 -20
  76. package/docs/cost.md +3 -3
  77. package/docs/developing.md +27 -9
  78. package/docs/doctor-codes.md +3 -1
  79. package/docs/export.md +2 -0
  80. package/docs/getting-started.md +44 -27
  81. package/docs/hosting.md +89 -43
  82. package/docs/images/brain.jpg +0 -0
  83. package/docs/images/home.jpg +0 -0
  84. package/docs/images/org.jpg +0 -0
  85. package/docs/images/prompt.jpg +0 -0
  86. package/docs/images/staff.jpg +0 -0
  87. package/docs/manual-steps.md +3 -2
  88. package/docs/org-yaml.md +3 -0
  89. package/docs/portal.md +143 -45
  90. package/docs/prompts.md +6 -0
  91. package/docs/security.md +57 -11
  92. package/docs/session-workflow.md +14 -0
  93. package/docs/staff-yaml.md +17 -1
  94. package/docs/upgrading.md +3 -3
  95. package/docs/writing-a-charter.md +19 -6
  96. package/package.json +4 -3
  97. package/templates/brain/.github/workflows/%%STAFF%%-daily.yaml +20 -1
  98. package/templates/brain/.github/workflows/%%STAFF%%-mention.yaml +53 -13
  99. package/templates/brain/staff.yaml +4 -1
  100. package/templates/briefs/amend.md +4 -3
  101. package/templates/briefs/priorities.md +46 -0
  102. package/templates/ops/.github/workflows/session.yaml +137 -3
  103. package/templates/ops/compose.mjs +35 -8
  104. package/templates/ops/org/operating.md +29 -10
  105. package/templates/ops/prompts/daily.md +23 -4
  106. package/templates/ops/prompts/mention.md +19 -0
  107. package/templates/ops/run-record.mjs +5 -3
  108. package/templates/portal/css/base.css +34 -0
  109. package/templates/portal/css/health.css +14 -1
  110. package/templates/portal/css/home.css +101 -0
  111. package/templates/portal/css/inbox.css +21 -4
  112. package/templates/portal/css/layout.css +29 -3
  113. package/templates/portal/css/markdown.css +19 -0
  114. package/templates/portal/css/search.css +48 -0
  115. package/templates/portal/css/setup.css +79 -4
  116. package/templates/portal/index.html +15 -9
  117. package/templates/portal/js/api.js +30 -4
  118. package/templates/portal/js/app.js +90 -7
  119. package/templates/portal/js/dialog.js +36 -0
  120. package/templates/portal/js/homesort.js +174 -0
  121. package/templates/portal/js/icons.js +41 -0
  122. package/templates/portal/js/inflight.js +18 -0
  123. package/templates/portal/js/md.js +5 -2
  124. package/templates/portal/js/mdedit.js +84 -0
  125. package/templates/portal/js/readiness.js +70 -0
  126. package/templates/portal/js/refresh.js +10 -2
  127. package/templates/portal/js/search.js +366 -0
  128. package/templates/portal/js/state.js +11 -5
  129. package/templates/portal/js/views/app.js +1 -2
  130. package/templates/portal/js/views/brain.js +1 -1
  131. package/templates/portal/js/views/checklist.js +19 -4
  132. package/templates/portal/js/views/credential.js +42 -51
  133. package/templates/portal/js/views/health.js +11 -6
  134. package/templates/portal/js/views/hire.js +593 -0
  135. package/templates/portal/js/views/home.js +585 -0
  136. package/templates/portal/js/views/inbox.js +237 -68
  137. package/templates/portal/js/views/org.js +31 -111
  138. package/templates/portal/js/views/orgedit.js +240 -0
  139. package/templates/portal/js/views/paste.js +111 -66
  140. package/templates/portal/js/views/prompt.js +94 -40
  141. package/templates/portal/js/views/repos.js +10 -10
  142. package/templates/portal/js/views/runs.js +21 -4
  143. package/templates/portal/js/views/setup.js +130 -163
  144. package/templates/portal/js/views/staff.js +181 -301
  145. package/templates/portal/js/views/todo.js +62 -0
package/docs/portal.md CHANGED
@@ -10,19 +10,33 @@ sidebar_order: 17
10
10
  roster # or `roster portal`, or `npx @nanocollective/roster`
11
11
  ```
12
12
 
13
- A local web UI over the checked-out repositories. Reads them from disk, so it needs no
14
- authentication and no API quota, and works offline. It can write to GitHub through your own
15
- `gh`. See [hosting](hosting.md) for why it stays local.
13
+ A web UI over every staff member's brain, read from GitHub as you. It needs no checkout to show
14
+ the org, and it acts on GitHub with your own token, so a reply here is the same as a reply on the
15
+ site. Setting up, hiring and doctor still use the checkout, so keep the repos checked out beside
16
+ each other, in the same shape the runner uses.
16
17
 
17
- Keep the repos checked out beside each other, in the same shape the runner uses.
18
+ It can also be hosted, on your own URL behind Sign in with GitHub: see [hosting](hosting.md).
18
19
 
19
20
  ## The sidebar
20
21
 
22
+ **Search everything** with ⌘K (Ctrl+K off a Mac), from anywhere, or the Search field at the
23
+ top of the sidebar, which opens the same dialog. It searches as you type, across:
24
+
25
+ - issues and pull requests, open and recently closed, which open in the side sheet
26
+ - staff, every fact in every memory, and every note and file in every brain
27
+ - the org files, the docs (every page, not only titles), and runs from the last 30 days, which
28
+ open their log on GitHub
29
+ - the screens themselves, so it doubles as a way to get anywhere
30
+
31
+ Every word has to match; a title that starts with one ranks first. Arrow keys move, Enter opens,
32
+ Escape closes. Everything except the docs is searched in the page, from what the portal has
33
+ already read.
34
+
21
35
  Anything that asks before it acts (a merge, a push, a hire, a retire, a paid run) asks in the
22
36
  page's own dialog, never the browser's `confirm()`, which blocks the whole tab.
23
37
 
24
- **The counts are right on load.** The badges beside Inbox and Pending work are fetched once at
25
- boot, and the Inbox screen shares that request rather than making a second one. A sidebar that
38
+ **The counts are right on load.** The badges beside Home and Trackers are fetched once at
39
+ boot, and the screens share that request rather than making a second one. A sidebar that
26
40
  says nothing until you look at it is not a sidebar.
27
41
 
28
42
  While the first answer is outstanding the badge is a placeholder rather than blank, because an
@@ -78,23 +92,71 @@ staff member* first, then the Actions setting, the credential, the repo picker,
78
92
  what doctor still says. A link to another screen still wins. When the list is empty the entry
79
93
  goes away; the repo picker lives on under [Org](#org).
80
94
 
81
- ## Inbox
95
+ ## Home
96
+
97
+ ![Home: latest reports, what needs you, and the Ask box](images/home.jpg)
98
+
99
+ Where the portal opens. An Ask box at the top, then these, in order.
100
+
101
+ - **Ask.** Pick a staff member, type what you want, **Send**. It opens an issue on their
102
+ tracker with their `@handle` in front, which wakes them in about a minute.
103
+ - **Latest reports.** Each staff member's run report from the last day: the three lines they
104
+ post on their status issue at the end of a daily run, with the issues and pull requests it
105
+ names as links. Click a report to open their status issue. Nothing shows until there is one.
106
+ - **Needs you.** Every ask a staff member has put on you, and every pull request ready to
107
+ merge, oldest first. Each card has one action on its right:
108
+ - a `decision` has **Reply**, and **Go with the default** when it carries one. The default
109
+ and its date are shown, and turn amber once the date has passed.
110
+ - a `review` has **Approve**.
111
+ - a `chore` has **Done**, which closes it.
112
+ - a pull request has **Merge**, unless its checks fail, are still running, or it conflicts.
113
+ Where the branch rules require an approving review, it also has **Approve**, and Merge waits
114
+ until you have pressed it. Approving is your review, given on purpose; Merge never gives it
115
+ for you.
116
+
117
+ Answers go out as you, with the staff member's `@handle`, so they act on them straight away.
118
+ Once you have had the last word, the card leaves Needs you for Your requests, since it is
119
+ waiting on them now. If they reply, it comes back. When nothing is waiting, it says so.
120
+ - **Unread.** Anything on a staff member's own tracker, or elsewhere, with activity you have not
121
+ seen: a peer's ask, a status issue, their own work. Unread comes from your GitHub
122
+ notifications, as on Trackers. Cards and rows anywhere on Home carry the same blue mark, and
123
+ opening one marks it read here and on GitHub.
124
+ - **Working now.** Each staff member: what they are running and what started it (the daily run,
125
+ a follow-on, answering an issue, a peer's ask), for how long, with a link to the log. When
126
+ they are idle, how their last run ended. Peer and follow-on runs today are counted against
127
+ `max_runs_per_day`. This asks GitHub every few seconds while a run is going and every half
128
+ minute otherwise, and only while Home is on screen.
129
+ - **Your requests.** What you asked for, and asks of theirs you have answered: waiting, being worked on (a run for it is going), or
130
+ answered (a staff member had the last word).
131
+ - **Closed today.** What the staff closed today, with the line they closed it with, and
132
+ **Reopen** beside each. Staff close finished issues themselves, so this is where you check.
133
+
134
+ **Every item opens in a side sheet.** Click anywhere on a card or a row and its thread opens
135
+ on the right: the conversation, Reply, Close or Reopen, Merge for a pull request, and Open in
136
+ GitHub. Escape or the × closes it, and Home repaints where you were.
137
+
138
+ **Nothing is missed.** Every open issue and pull request has exactly one place: on Home, or on
139
+ the staff member's own tracker (their status issue, a peer's ask, their own work), or elsewhere
140
+ (draft pull requests, contributor issues). The line at the bottom counts the last two, with a
141
+ link to Trackers.
142
+
143
+ ## Trackers
82
144
 
83
145
  Everything open across the org, from one GraphQL call per repo. Bodies and full timelines come
84
146
  down with the list, so opening a thread is a render rather than a request.
85
147
 
86
- - **Filter by staff member.** An item belongs to somebody if it is in their brain repo, their
87
- own App wrote it, a peer addressed it to them with a `from-<handle>` label, or it is assigned
88
- to them. The shared public identity cannot name one staff member, so an item it wrote counts
89
- for anyone who works in that repo. Items authored by humans belong to nobody, which is
90
- correct.
91
- - **Scope** to everything, what is assigned to you, decisions, or open PRs.
92
- - **Open, recently closed, or both.** Open by default: an inbox is what is waiting on
148
+ - **The links under Trackers in the sidebar filter it.** All; Unread; each staff member, which
149
+ lists the issues on their own tracker whoever filed them; and Issues, the product repos.
150
+ - **Unread comes from your GitHub notifications.** A thread with activity you have not read has
151
+ a bar on the left and a bold title, and Unread lists only those, with a count. Opening one
152
+ marks it read on GitHub too, and reading it on GitHub clears it here. GitHub only notifies you
153
+ about repos you watch and threads you are part of.
154
+ - **Open or closed.** Open by default: an inbox is what is waiting on
93
155
  somebody, and months of finished work mixed into that answers a different question. Closed
94
156
  work reaches back 45 days, up to 30 issues and 30 pull requests per repository, and carries
95
157
  a shorter timeline than open work because it is there to be read rather than triaged. A
96
158
  closed row is dimmed and marked; the sidebar badge keeps counting only what is open.
97
- - **Reply, close, reopen, open an issue.** All as you, through your own `gh`, so they are
159
+ - **Reply, close, reopen, open an issue.** All as you, with your own token, so they are
98
160
  indistinguishable from doing it on the site. Closing asks for confirmation. A half-written
99
161
  reply survives a repaint, and pressing Comment with an empty box says so rather than
100
162
  silently doing nothing.
@@ -144,7 +206,7 @@ down with the list, so opening a thread is a render rather than a request.
144
206
 
145
207
  ## Pending work
146
208
 
147
- The same screen, scoped to pull requests, in its own place in the sidebar. An inbox is what is
209
+ The same screen, scoped to pull requests. It is where a pull request opens from Home. An inbox is what is
148
210
  waiting on you; a pull request is work that is finished and waiting on a merge, and the count
149
211
  that matters is not how many are open but how many are green and still sitting there.
150
212
 
@@ -201,7 +263,7 @@ On the **Files** tab each file's heading has its own Reply, which opens the same
201
263
  one file. "This bit is wrong" is what you want to say while looking at a diff, and the
202
264
  alternative is describing in prose which of thirty files you meant.
203
265
 
204
- Both writes go through your own `gh`, as you. Nothing is dispatched between repositories and no
266
+ Both writes are yours, made with your own token. Nothing is dispatched between repositories and no
205
267
  credential is put on a public repo. The tracker issue goes first, because it is the half that
206
268
  reaches anybody; if the copy on the pull request then fails you are told, rather than being
207
269
  shown an error that invites you to ask the same person the same thing twice.
@@ -213,13 +275,19 @@ it took, turns and cost where known, and a link to the log. Above the tables, th
213
275
  for the org, and each staff member's own in their heading.
214
276
 
215
277
  Runs are not in any repo, so this is the one screen that is only ever on GitHub. It reads the
216
- run lists through your own `gh`, the same way the inbox does, and offline it says so rather
217
- than drawing an empty table that reads as "nothing ran".
278
+ run lists as you, the same way the inbox does, and when GitHub cannot be reached it says so
279
+ rather than drawing an empty table that reads as "nothing ran".
218
280
 
219
281
  Cost comes from the record each run leaves behind (see [cost](cost.md#what-each-run-cost)). A
220
282
  run from before records existed, or from an agent that does not report cost, shows a dash, and
221
- a total says how many runs it could price. Each record is downloaded once and kept for as long
222
- as the portal runs, so the first visit is the slow one.
283
+ a total says how many runs it could price. Each record is downloaded once, ever, and kept in
284
+ `~/.cache/roster/runs` (or `ROSTER_CACHE_DIR`), since a finished run's record never changes.
285
+ The table shows at once with the costs already known; any not yet read are fetched in the
286
+ background, and the screen says how many and fills them in as they arrive.
287
+
288
+ The run list asks GitHub for each outcome separately (succeeded, failed, cancelled and so on)
289
+ rather than paging through every run, because most of a mention caller's runs are comments that
290
+ woke nobody and were skipped.
223
291
 
224
292
  A skipped mention is not a run and is not listed. A `setup-failure` is a run that failed before
225
293
  the agent started, usually a token or a checkout. Past a [`budget`](org-yaml.md#budget), the
@@ -236,7 +304,7 @@ heading.
236
304
  typing `role: product` into `org.yaml` by hand. Adding one commits `org.yaml` and pushes. A new
237
305
  hire picks it up; somebody already hired keeps the `works_in` in their own `staff.yaml`.
238
306
 
239
- **The list comes off disk**, not out of the page, so a tenant that adds `org/pricing.md` can
307
+ **The list comes from the ops repo**, not out of the page, so a tenant that adds `org/pricing.md` can
240
308
  open it like any other. Only files the
241
309
  portal may actually write are listed: an editor that offers a file it cannot save is a trap.
242
310
 
@@ -262,21 +330,48 @@ have more than one human, and a card that names one of two reads as the only one
262
330
 
263
331
  Everyone on the roster, and the things you would otherwise do from a terminal.
264
332
 
265
- **Hiring** runs the same `buildPlan` and `applyPlan` that `roster hire` does, on the server.
266
- Only the handle is required; everything else is copied from whoever is already here. The first
267
- hire has nobody to copy App names from, so its form also asks for the App's name and the shared
268
- public App's, which are `--app` and `--public-app`. The public one only matters when a product
269
- repo is public; on private ones the session uses the staff member's own App. You see
270
- the plan first, listing every file, every label, the schedule it chose and why, the commits it
271
- will make as you in repos that already exist (each peer's `staff.yaml`, `org.yaml`), whether the
272
- new brain joins the credential's org secret, and what is left for you. Nothing happens until you
273
- apply. What the terminal would have printed is shown when it finishes.
333
+ **Hiring** starts from a role. With nobody hired the Staff screen opens on the role picker;
334
+ after that it is behind **Hire someone**. The cards are CTO, CMO and Support, each with a line
335
+ on what they do, and **Something else**, which asks for the role's name and a sentence about it.
336
+ A role that is already hired is not offered. Picking one fills in the handle, name and repo
337
+ (`cto`, `cmo`, `support`, or a handle made from the name) and leaves the schedule empty, so the
338
+ server picks a free slot. All four are under **Advanced**, still editable. The first hire has
339
+ nobody to copy App names from, so Advanced also holds the App's name and the shared public
340
+ App's, which are `--app` and `--public-app`, filled in as `<org>-<handle>` and `<org>-robot`.
341
+ The public one only matters when a product repo is public; on private ones the session uses the
342
+ staff member's own App.
343
+
344
+ The role opens a numbered list on the same screen:
345
+
346
+ 1. **Hire.** One sentence from the plan: the repo it creates and when it runs. **Show details**
347
+ has the full plan, from the same `buildPlan` and `applyPlan` that `roster hire` runs on the
348
+ server: every file, every label, the schedule and why, the commits it makes as you in repos
349
+ that already exist (each peer's `staff.yaml`, `org.yaml`), and whether the new brain joins
350
+ the credential's org secret. **Hire** asks before it acts.
351
+ 2. **Create their GitHub App.** The private App, and the shared public one only when a product
352
+ repo in `org.yaml` is public (or has no visibility written, which hire treats as public).
353
+ 3. **Write their charter.** Three tabs: an AI interview (the default), the matching worked
354
+ example with your business's name in place of Acme's, and the file itself. A role that
355
+ matches no example has no template tab.
356
+ 4. **Add your agent credential.** Only while none is stored.
357
+ 5. **Run once now.**
358
+
359
+ Steps 2 to 5 say *Hire first* until the hire is done. Each step's Done comes from real data:
360
+ the hire from the staff member appearing in `org.yaml`, the charter from `CHARTER.md` no longer
361
+ being the stub (the same test as doctor's `charter.stub`), the App from its `_APP_ID` secret on
362
+ the brain repo, the credential from the org secret, and the run from a successful daily run.
363
+ After **Hire** the screen reloads the org and stays on the same staff member, on step 2.
364
+
365
+ A card whose setup is not finished (a stub charter, no App secrets, or no successful run yet)
366
+ shows **Finish setting up**, which opens the same list for them. The App secrets and the run
367
+ are read from GitHub.
274
368
 
275
369
  **Writing the charter** is the copy-a-prompt loop below, aimed at `CHARTER.md`. `hire`
276
370
  deliberately does not write it, because a generated charter produces exactly the generic agent
277
371
  this whole arrangement exists to avoid. It is the same brief as `roster brief charter
278
372
  <handle>`, with somewhere to put the answer, and a picker for the worked example it carries as a
279
- model: matched to the role, or another, or none.
373
+ model: matched to the role, or another, or none. For a role added with **Something else**, the
374
+ sentence you typed goes into the brief.
280
375
 
281
376
  **The GitHub App** is `roster app`, on this server rather than a second one. There is no API that
282
377
  creates an App: the only route is the manifest flow, where you post a manifest to a settings page,
@@ -312,7 +407,7 @@ already declared `memory/` as a surface.
312
407
  The navigator has three boxes, because a parsed memory section and a file on disk are
313
408
  different kinds of thing.
314
409
 
315
- **Memory** is the fact sections, the notes behind them, and `INDEX.md` itself. A note is the
410
+ **What they know** is the fact sections, the notes behind them, and `INDEX.md` itself. A note is the
316
411
  argument behind one fact, read only when that fact is in play, which is what keeps the index
317
412
  cheap enough to read at every boot. Both live here rather than among the files: `INDEX.md` is
318
413
  literally what "All facts" renders.
@@ -358,11 +453,15 @@ half complaints answered neither well.
358
453
 
359
454
  ### Getting help changing it
360
455
 
361
- **Copy a brief for changing this** asks what you want changed, in a box big enough to say it
362
- in, and copies the same thing: a
363
- self-contained prompt carrying the composed text, every layer with its path and blast radius,
364
- and what may and may not be edited. `roster brief amend <handle> --want "…"` prints the same
365
- from the terminal.
456
+ **Change this with your AI** opens a side sheet in three steps:
457
+ 1. What you want changed, in a box big enough to say it in.
458
+ 2. **Copy the prompt**: a self-contained brief carrying the composed text, every layer with its
459
+ path and blast radius, and what may and may not be edited. It only copies. The prompt as it
460
+ composes today is under it, to read first.
461
+ 3. Paste your AI's reply. It hands back whole files, which are checked against the layers this
462
+ prompt is made of and shown as diffs, each with Save. Nothing is written until you press it.
463
+
464
+ `roster brief amend <handle> --want "…"` prints the same brief from the terminal.
366
465
 
367
466
  It carries the state rather than asking for it, because working out which of eight files to
368
467
  open is the difficulty being solved. A brief that says "read your layers first" has handed
@@ -370,8 +469,9 @@ that straight back.
370
469
 
371
470
  ### Editing
372
471
 
373
- Layers are editable in place. Saving writes the file, commits **only that file**, and pushes,
374
- as you, through your own git. The confirmation names the repository and says who picks it up:
472
+ Layers are editable in place. Saving commits **only that file** to GitHub, as you. If
473
+ the file has changed on GitHub since you opened it, the save is refused and says to reload,
474
+ rather than overwriting somebody else's edit. The confirmation names the repository and says who picks it up:
375
475
  every staff member for anything under `org/` or `prompts/`, one staff member for a brain file.
376
476
 
377
477
  The writable set is an allowlist, because this commits to repositories the agents run from:
@@ -481,11 +581,9 @@ worse than no linter. A finding true of more than one prompt is one row, and it
481
581
  | it names a file that is not there | an instruction to read something absent is a quiet no-op inside a run nobody watches |
482
582
  | an included layer is empty | it contributes nothing and costs a line of includes |
483
583
 
484
- **Every finding carries the fix.** "Copy a prompt to fix this" builds a brief containing the
485
- finding, the composed prompt, and every layer, and puts it on your clipboard. Paste it into
486
- whatever agent you use. Knowing there is a problem is the hard part; writing the paragraph is
487
- not. The box comes pre-filled with what the finding worked out, so you can add to it rather
488
- than retype it. "Open the file" takes you to that layer on the Prompt screen.
584
+ **Every finding carries the fix.** "Fix this with your AI" opens the same sheet as the Prompt
585
+ screen's, with the finding at the top and the box pre-filled with what it worked out, so you
586
+ can add to it rather than retype it. Copy the prompt, paste the reply back, save the diff. "Open the file" takes you to that layer on the Prompt screen.
489
587
 
490
588
  **Memory problems** are the same checks `roster lint` runs. Each one has a button that opens an
491
589
  issue in that staff member's own repo asking them to fix it, which is usually right, because
package/docs/prompts.md CHANGED
@@ -99,6 +99,12 @@ than a hang.
99
99
  | `ops.dir` | ops repo directory in the checkout |
100
100
  | `staff` | the whole of this staff member's `staff.yaml` |
101
101
  | `staff.dir` | where their brain lands in the checkout |
102
+ | `staff.handle`, `staff.name` | their handle (`cto`) and role name (`Chief Technology Officer`) |
103
+ | `staff.brain` | their brain repo, `owner/name` |
104
+ | `staff.bot` | the login they post as on private repos, e.g. `acme-cto[bot]` |
105
+ | `staff.public_bot` | the login they post as on public repos |
106
+ | `staff.public_token_env` | the environment variable holding the public repo token during a run |
107
+ | `staff.status_issue` | the number of their pinned status issue |
102
108
  | `staff.product` | **first entry of `works_in`, or null** |
103
109
  | `staff.product.repo` | that repo's `owner/name` |
104
110
  | `peers` | list of the other staff members |
package/docs/security.md CHANGED
@@ -16,9 +16,14 @@ What can reach what, and what stops it.
16
16
  | Public App private key | a repo secret | mint a token for the public product repo |
17
17
  | Agent credential | a repo secret | spend money with your model provider |
18
18
  | Your `gh` token | your machine | whatever you can |
19
+ | A hosted portal's sign-in | a sealed cookie in your browser | whatever you can |
20
+ | The portal's OAuth App secret and session key | Worker secrets | sign people in |
19
21
 
20
- **No credential is held by roster.** The CLI and the portal shell out to your own `gh`. The
21
- framework has no service, no server it talks to, and nothing to store.
22
+ **On your machine, no credential is held by roster.** The CLI uses your own `gh`, and the
23
+ portal asks `gh` for its token once, holds it in memory, and writes it nowhere.
24
+
25
+ **A hosted portal holds each person's sign-in, and nothing else.** See
26
+ [the hosted portal](#the-hosted-portal).
22
27
 
23
28
  ## The App private key
24
29
 
@@ -55,17 +60,25 @@ The rule: **the default branch of every product repo requires a pull request wit
55
60
  approving review, and no staff App is on the list of who may bypass it.** A ruleset or classic
56
61
  branch protection both count.
57
62
 
58
- `roster doctor` reads it for every `role: product` repo in `org.yaml` and every repo a staff
63
+ **It is off unless you turn it on**, with `review_gate: true` in `org.yaml`. Without it, staff
64
+ are told to leave merging to you, and on Pip they always have, but GitHub does not stop them.
65
+ Most orgs keep product repos private on the Free plan, where GitHub cannot enforce the rule.
66
+
67
+ With it on, `roster doctor` reads it for every `role: product` repo in `org.yaml` and every repo a staff
59
68
  member `works_in`, as `review-gate`. It fails when nothing requires a PR or a staff App can
60
69
  bypass the rule, and warns when a PR is required with no approval, since then whoever opened
61
70
  it can merge it.
62
71
 
63
- `roster hire --apply` adds a ruleset named `roster: review before merge` to each product repo
72
+ With it on, `roster hire --apply` adds a ruleset named `roster: review before merge` to each product repo
64
73
  that does not already require an approving review, and leaves anything stricter alone. Pass
65
74
  `--no-review-gate` to skip it. The ruleset lets repository admins bypass it only by merging a
66
75
  pull request, so your own merge is still the approval (GitHub will not let you approve your
67
76
  own PR) and an App, which is never an admin, cannot merge at all.
68
77
 
78
+ **On GitHub Free, private repos can't have this rule.** GitHub only enforces rulesets and
79
+ branch protection on private repos for paid plans. To use the gate there, make the product repo
80
+ public or move the org to GitHub Team.
81
+
69
82
  To set it by hand: repo **Settings -> Rules -> Rulesets -> New branch ruleset**, target the
70
83
  default branch, tick **Require a pull request before merging** with one required approval, and
71
84
  keep the staff Apps off the bypass list.
@@ -89,8 +102,8 @@ Never verify an installation by reading the API. The only proof is a run that fi
89
102
 
90
103
  The setup screen creates repositories, creates GitHub Apps and writes repository secrets. It is
91
104
  the most privileged surface roster has, and it is **local only**: bound to `127.0.0.1`, behind the
92
- same write guard as everything else, and never something to put behind a tunnel. There is no
93
- hosted setup and there should not be.
105
+ same write guard as everything else, and never something to put behind a tunnel. A hosted
106
+ portal does not have it, nor hiring, retiring or doctor.
94
107
 
95
108
  The App manifest hand-off runs on the portal's own port rather than a second one, which changes
96
109
  where the callback lands and nothing else: the one-time code is still exchanged server-side, and
@@ -102,14 +115,13 @@ callback whose state is unknown is refused.
102
115
 
103
116
  It can write to GitHub, so it is worth being precise.
104
117
 
105
- It binds to `127.0.0.1`. A write needs a `POST`, an `x-roster` header (which forces a CORS
118
+ On your machine, it binds to `127.0.0.1`. A write needs a `POST`, an `x-roster` header (which forces a CORS
106
119
  preflight that fails from any other origin), and an `Origin` that is either absent or
107
120
  localhost. Reads are served to anything that can reach the port.
108
121
 
109
- Two paths take attacker-controlled input to the disk or a command line, and both are
110
- constrained rather than sanitised:
122
+ These paths take attacker-controlled input, and each is constrained rather than sanitised:
111
123
 
112
- - `/api/file` resolves the path and refuses anything outside the workspace root.
124
+ - `/api/file` resolves the path and refuses anything outside the org's repositories.
113
125
  - `/api/diff` requires the directory to be a known staff repo and the sha to look like a sha.
114
126
  - `/api/doc` requires the page to be one the listing offered.
115
127
  - `/api/docasset` requires the screenshot to be one sitting in `docs/images/`, matched by name
@@ -118,6 +130,40 @@ constrained rather than sanitised:
118
130
  `--host` overrides the bind address and prints a warning. It exists for people who know what
119
131
  they are doing on a network they control. See [hosting the portal](hosting.md).
120
132
 
133
+ A save says what text the edit started from, and is refused if the file has moved on GitHub
134
+ since, so the portal never overwrites somebody else's change without saying so.
135
+
136
+ ## The hosted portal
137
+
138
+ The same portal on Cloudflare Workers, behind Sign in with GitHub.
139
+
140
+ **Who gets in.** The people in `org.yaml`'s `humans:`, signed in through an OAuth App the org
141
+ creates. Membership is checked with their own token at sign-in, which also proves they can read
142
+ the ops repo, and again every few minutes. Anybody else is turned away and their token revoked.
143
+
144
+ **What it holds.** Each person's GitHub token, their login and an expiry, sealed with AES-GCM
145
+ under the Worker's `SESSION_KEY` and set as an `HttpOnly`, `Secure`, `SameSite=Lax` cookie.
146
+ There is no database. A cookie that was tampered with, or sealed under another key, does not
147
+ open. Rotating `SESSION_KEY` signs everybody out. The OAuth App's client secret is a Worker
148
+ secret and is used only to finish a sign-in and to revoke a token.
149
+
150
+ **What a write needs.** A `POST`, the `x-roster` header, an `Origin` that is the portal's own,
151
+ and a signed-in session. `SameSite=Lax` keeps the cookie off cross-site posts as well.
152
+
153
+ **What it can do if somebody reaches it.** Without a sign-in, nothing but show the sign-in page
154
+ and the page's own scripts. With one, only what that person's GitHub account can already do:
155
+ every read and write goes to GitHub with their token, so GitHub's own permissions are the
156
+ boundary. It cannot set up an org, create an App, write a secret, hire or retire.
157
+
158
+ **What it shares between people.** The copy it holds of the org's repositories is shared by
159
+ everyone signed in, as is the cache. Everyone signed in is one of the org's humans, so this is
160
+ the org shown to its own people; a human whose GitHub account cannot read one of the brains can
161
+ still see that brain in the portal. Their unread marks and anything they do are their own.
162
+
163
+ **The OAuth scopes.** `repo` and `notifications`. A GitHub App would be narrower, but its
164
+ tokens cannot read notifications, and unread in the portal is GitHub's own unread, kept in step
165
+ with the website and your phone.
166
+
121
167
  ## Trust in a prompt
122
168
 
123
169
  Everything composed into a prompt is content you or your agents wrote: `org/`, the charter, the
@@ -133,7 +179,7 @@ So a mention on a public pull request is decoration. It posts, it renders as a c
133
179
  nothing happens, which is safe and also invisible. The portal is what makes it visible and what
134
180
  gets you out of it: replying with an `@handle` where nothing listens says so, and offers to
135
181
  open the request on that person's own private tracker as well, carrying the pull request and
136
- the hunk. It writes through your own `gh`, as you, so no credential lives on the
182
+ the hunk. It writes as you, with your own token, so no credential lives on the
137
183
  public repo and nothing is dispatched across a boundary.
138
184
 
139
185
  If you add a workflow to a product repo that bridges this automatically, its author gate is
@@ -33,6 +33,8 @@ repositories in this organisation**. Without it, callers fail with "workflow not
33
33
  | `allowed_tools` | string | `Bash,Read,Write,Edit,Glob,Grep,WebFetch,WebSearch` | Tool permissions, for agents that take them. |
34
34
  | `issue_number` | string | `""` | Trigger context. |
35
35
  | `comment_id` | string | `""` | Trigger context. |
36
+ | `trigger` | string | `""` | What started the run: `daily`, `manual`, `follow-on`, `mention` or `peer`. Passed to the prompt. |
37
+ | `max_runs_per_day` | number | `6` | How many `peer` and `follow-on` runs may start in a UTC day. Mentions are never counted. |
36
38
 
37
39
  ## Secrets
38
40
 
@@ -51,6 +53,14 @@ authentication error forty lines into a log.
51
53
 
52
54
  ## What it does, in order
53
55
 
56
+ Before the session job, a small **budget** job. For a `peer` or `follow-on` run it counts this
57
+ brain's runs today with those names in their `run-name`, this one included and skipped ones
58
+ left out. Over `max_runs_per_day`, the session does not start and the issue that woke it gets a
59
+ comment saying so. If the runs cannot be read, the run does not start either: a run held back
60
+ costs a day, and a loop costs a bill. Every other trigger goes straight through.
61
+
62
+ Then the session:
63
+
54
64
  1. **Start the clock**, for the run record.
55
65
  2. **Mint the private-tracker token** from the staff member's App.
56
66
  3. **Mint the public-repo token**, if a public App was passed.
@@ -70,6 +80,10 @@ authentication error forty lines into a log.
70
80
  14. **Work out which agent runs this**, by running `agents.mjs`.
71
81
  15. **Run the session**, by one of two steps: the Action-based reference runner, or the generic
72
82
  CLI one. See [choosing a coding agent](agents.md).
83
+ Then, for a mention, **check the request was answered**: a reply in the thread, or the issue
84
+ closed. Neither fails the job, so the notice below tells the human.
85
+ Then, for a daily run that finished and wrote `.roster-run/continue`, **start a follow-on
86
+ run**: one more daily run with `trigger: follow-on`, which waits for this one to end.
73
87
  16. **Write down the run**, whatever happened: staff, kind, outcome, duration, and turns, cost
74
88
  and tokens where the agent reports them. Into the job summary, and kept as an artifact
75
89
  called `roster-run`. Never fatal. See [cost](cost.md#what-each-run-cost).
@@ -25,6 +25,7 @@ schedule: "0 7 * * 1-5"
25
25
  model: claude-opus-5-5
26
26
  timeout_minutes: 90
27
27
  mention_timeout_minutes: 90
28
+ max_runs_per_day: 6
28
29
 
29
30
  bot: acme-cto[bot]
30
31
  public_bot: acme-robot[bot]
@@ -49,7 +50,7 @@ surfaces:
49
50
 
50
51
  labels:
51
52
  owner: [will, cto, cmo]
52
- kind: [decision, setup, build, blocked]
53
+ kind: [decision, review, chore, keep-open, build, blocked]
53
54
  ```
54
55
 
55
56
  ## Identity
@@ -59,6 +60,7 @@ labels:
59
60
  | `handle` | yes | Must match `org.yaml`. The composer looks them up by the `org.yaml` one, so a mismatch composes the wrong brain. |
60
61
  | `name` | yes | Role name in prose. |
61
62
  | `mention` | yes | What wakes them, as in `@cto`. The caller's condition tests for this string. |
63
+ | `icon` | no | The icon the portal shows for them: `code`, `megaphone`, `life-buoy`, `compass`, `brush`, `bug`, `server`, `book-open`, `bar-chart`, `users` or `person`. Unset, it is picked from the role. |
62
64
  | `brain` | yes | `owner/name` of this repo. Without it nothing can check secrets, labels or runs. |
63
65
  | `status_issue` | yes in practice | Number of the pinned status issue. The prompts reference it, so a run cannot compose without it. `roster hire --apply` writes it. |
64
66
 
@@ -70,6 +72,7 @@ labels:
70
72
  | `model` | org default | Model id. |
71
73
  | `timeout_minutes` | 90 | Ceiling on the daily session. |
72
74
  | `mention_timeout_minutes` | 90 | Ceiling on a mention run. |
75
+ | `max_runs_per_day` | 6 | Runs a UTC day that start without a person asking: a peer's ask, or a follow-on to a daily run. Mentions never count. Rendered into the callers, so change it and run `roster upgrade`. |
73
76
 
74
77
  The three ceilings are separate on purpose. Raising the daily one because sessions have grown
75
78
  should not double the budget for a PR amendment. A job killed by a ceiling is reported by
@@ -154,6 +157,19 @@ Labels this staff member expects to exist on its own tracker, grouped for readab
154
157
  value across every group is checked by `roster doctor`. An agent applying a label that does not
155
158
  exist gets an API error mid-run.
156
159
 
160
+ Four labels are roster's own and are checked on every tracker whatever this lists:
161
+
162
+ | Label | Means |
163
+ |---|---|
164
+ | `decision` | An ask for the human to rule on. It carries a default and a date; past the date, the staff member acts on the default and closes it. |
165
+ | `review` | An ask for the human to read or approve something. |
166
+ | `chore` | Something only the human can do: a setting, an account, a key. |
167
+ | `keep-open` | A standing thread. A sweep never closes it. `roster hire` puts it on the status issue. |
168
+
169
+ Every ask on the human carries exactly one of the first three, which is how the portal sorts
170
+ what needs them. Staff close any issue on their tracker once nothing is left to do on it,
171
+ including the human's requests, with one line saying what closed it.
172
+
157
173
  ## `memory`
158
174
 
159
175
  This staff member's own memory budgets, overriding the org's. Same three fields as
package/docs/upgrading.md CHANGED
@@ -10,9 +10,9 @@ The framework writes templates out. A tenant runs its own copies. So the two dri
10
10
  `roster upgrade` is what reconciles them without eating your edits.
11
11
 
12
12
  ```bash
13
- roster upgrade # what would change
14
- roster upgrade --apply # do it
15
- roster upgrade --check # exit non-zero if anything is pending (for CI)
13
+ npx @nanocollective/roster@latest upgrade # what would change
14
+ npx @nanocollective/roster@latest upgrade --apply # do it
15
+ npx @nanocollective/roster@latest upgrade --check # exit non-zero if anything is pending (for CI)
16
16
  ```
17
17
 
18
18
  ## How it decides
@@ -28,10 +28,10 @@ layer. That is the part that matters most, because without them the model writes
28
28
  of whoever it was shown. The brief then interviews you, drafts from your answers, and tells you
29
29
  what it cut and why.
30
30
 
31
- **So is a worked example, when one fits.** A staff member whose handle or role reads as a CTO, a
32
- CMO or support gets the matching [example](#worked-examples) inside the brief, labelled as a
31
+ **So is a worked example, when one fits.** A staff member whose handle or role reads as one of
32
+ the ten roles below gets the matching [example](#worked-examples) inside the brief, labelled as a
33
33
  model for the shape and not content to copy. The copy-a-prompt panel has a picker to choose
34
- another or none; in a terminal it is `--example cto|cmo|support|none`. It is still a brief you
34
+ another or none; in a terminal it is `--example <handle>` or `--example none`. It is still a brief you
35
35
  answer: the interview comes first, and nothing in the charter should come from the example
36
36
  rather than from you.
37
37
 
@@ -72,9 +72,22 @@ status issue, and the surfaces the manifest declares.
72
72
 
73
73
  ## Worked examples
74
74
 
75
- Three, for an invented company called Acme: a [CTO](charters/cto.md), a [CMO](charters/cmo.md)
76
- and a [Head of Support](charters/support.md). They are examples to adapt, not templates to fill
77
- in. Read them for what a finished charter covers and how specific it gets, then write your own
75
+ Ten, for an invented company called Acme. The handle in brackets is the one `--example` takes.
76
+
77
+ | Example | What they do |
78
+ |---|---|
79
+ | [CTO](charters/cto.md) (`cto`) | Builds the product: fixes, features and tests, as pull requests. |
80
+ | [CMO](charters/cmo.md) (`cmo`) | Posts, SEO, copy and launch plans, as drafts to approve. |
81
+ | [Head of Support](charters/support.md) (`support`) | Answers issues, writes help docs, and turns user reports into bugs. |
82
+ | [Product Manager](charters/pm.md) (`pm`) | Turns ideas and user feedback into clear specs and a ranked backlog. |
83
+ | [Designer](charters/designer.md) (`designer`) | Improves the product's look and usability, with accessibility fixes, as pull requests. |
84
+ | [QA Engineer](charters/qa.md) (`qa`) | Tests the product, finds bugs, and writes clear reproductions and tests. |
85
+ | [DevOps Engineer](charters/devops.md) (`devops`) | Keeps CI, deploys and dependencies healthy, and patches security updates. |
86
+ | [Technical Writer](charters/writer.md) (`writer`) | Writes and keeps up the docs, guides and changelog. |
87
+ | [Data Analyst](charters/analyst.md) (`analyst`) | Reads the numbers and writes a short weekly report on what changed. |
88
+ | [Community Manager](charters/community.md) (`community`) | Answers discussions, welcomes contributors, and drafts release announcements. |
89
+
90
+ They are examples to adapt, not templates to fill in. Read them for what a finished charter covers and how specific it gets, then write your own
78
91
  about your business. A charter copied from one of these describes Acme. The brief carries the matching one for
79
92
  you; these links are for reading them first.
80
93
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@nanocollective/roster",
3
- "version": "0.1.0-alpha.9",
3
+ "version": "0.1.0-beta.1",
4
4
  "description": "An agent-run org, powered by GitHub. Scaffold AI staff members whose brain is a repo.",
5
5
  "type": "module",
6
6
  "bin": {
@@ -17,7 +17,7 @@
17
17
  "node": ">=20"
18
18
  },
19
19
  "scripts": {
20
- "build": "tsup src/cli.ts --format esm --target node20 --clean",
20
+ "build": "tsup src/cli.ts --format esm --target node20 --clean && node scripts/build-worker.mjs",
21
21
  "dev": "tsx src/cli.ts",
22
22
  "test": "tsx --test test/*.test.ts",
23
23
  "test:all": "pnpm test:format && pnpm test:lint && pnpm test:types && pnpm test:knip && pnpm test",
@@ -31,7 +31,8 @@
31
31
  "test:security": "semgrep scan --config auto --error",
32
32
  "typecheck": "tsc --noEmit",
33
33
  "format": "biome check --write .",
34
- "prepublishOnly": "pnpm test:all && pnpm build"
34
+ "prepublishOnly": "pnpm test:all && pnpm build",
35
+ "build:worker": "node scripts/build-worker.mjs"
35
36
  },
36
37
  "devDependencies": {
37
38
  "@biomejs/biome": "^2.5.12",